Send File Extension API
This API issues the Send File or the Resend File.
Syntax
INT __stdcall utlsendex( LPCSTR lpszFileID , LPCSTR lpszHostName ,
BOOL bResend , SHORT nPriority , BOOL bSync , INT nWait ,
LPCSTR lpszFileName , LPCSTR lpszGroup , BOOL bNp ,
HULMSGS* lpMsg , INT nTransMode );
Explanation of the parameters
- LPCSTR lpszFileID (IN)
-
Specify the file ID of the file for which to carry out the Send File
Specify the file ID as a character string within 50 bytes. To omit this parameter, specify 'NULL.'
- LPCSTR lpszHostName (IN)
-
This is the parameter to dynamically specify the host name of the host on the receiving side in the case of the Send File or the host name in the case of the Resend File.
Specify the host name as a character string within 68 bytes.
You cannot specify this parameter and "lpszGroup" at the same time.
To use this parameter when you issue the Send File, specify 'Enable Dynamic Specification' for Dynamic Parameter Specification (dynparam) in the System Environment Settings file (hulenv.cnf).
For details on Dynamic Parameter Specification, refer to the following:
HULFT10 for Windows Administration Manual : Send and Receive
- BOOL bResend (IN)
-
Specify the resend flag
- TRUE:
-
Specify the Resend File
- FALSE:
-
Specify the Send File
- SHORT nPriority (IN)
-
Specify the transfer priority
Specify a value from '1' to '256.' To omit this parameter, specify '0.'
- BOOL bSync (IN)
-
Specify the synchronous transfer flag
For the Resend File (bResend = TRUE), you cannot specify Synchronous Transfer.
- TRUE:
-
Carry out Synchronous Transfer
- FALSE:
-
Do not carry out Synchronous Transfer
- INT nWait (IN)
-
Specify the time to wait for the Receive processing results for Synchronous Transfer (seconds)
When you specify the Synchronous Transfer, set the wait time for synchronizing the transfer with the result of processing, in the range from '10' to '259200.' When it reaches the time that you specified, HULFT resumes processing even if it is in the middle of sending. In this case, note that HULFT does not return the transfer results.
The parameter is enabled only when the Synchronous Transfer (bSync=TRUE) is specified. When you do not intend to carry out the Synchronous Transfer (bSync=FALSE), specify '0.'
When you specify '0' for this parameter, HULFT applies the set value of Socket Read Timeout (socktime) in the System Environment Settings file.
- LPCSTR lpszFileName (IN)
-
Specify the file name of the file to send or resend
Specify a file name with a full path within 200 bytes. To omit this parameter, specify 'NULL.'
In this case, HULFT applies the setting of Send File Name (FILENAME) that is registered in the Send Management Information when you issue the Send File. To use this parameter, specify 'Enable Dynamic Specification' for Dynamic Parameter Specification in the System Environment Settings file.
For details on Dynamic Parameter Specification, refer to the following:
HULFT10 for Windows Administration Manual : Send and Receive
For the Resend File, specify the file name of a file that is placed in the Resend Queue. This is not a parameter to dynamically specify the file to resend. If you do not specify this parameter, HULFT resends all transfers that match the host name or file ID specified by the parameters.
- LPCSTR lpszGroup (IN)
-
Specify the transfer group ID of the transfer
Specify the ID as a character string within 50 bytes.
You cannot specify this parameter and "lpszHostName" at the same time.
To omit this parameter, specify 'NULL.' In this case, HULFT applies the transfer group ID registered in Send Management Information to this parameter to execute the processing. To use this parameter, specify 'Enable Dynamic Specification' for Dynamic Parameter Specification in the System Environment Settings file.
For details on Dynamic Parameter Specification, refer to the following:
HULFT10 for Windows Administration Manual : Send and Receive
- BOOL bNp (IN)
-
Specify the Checkpoint flag
For the Send File (bResend=FALSE), be sure to specify 'FALSE.'
- TRUE:
-
Upon the Resend File request, the file transfer resumes from the beginning of the file
- FALSE:
-
Carry out the Checkpoint Resend File (file transfer resumes from the checkpoint)
- HULMSGS* lpMsg (IN)
-
Specify the message structure
For Resend File (bResend=TRUE), be sure to specify 'NULL'
Specify 'NULL' also to omit this parameter.
The details of the structure are as mentioned below.
When you do not use long messages, you do not need to include 'exmsginfo' in the message structure.
typedef struct _tagHULMSGS { DWORD msgcnt; // Number of messages that are stored CHAR** msginfo; // Message table ($MSG0 to $MSG5) CHAR** exmsginfo; // Long Message table ($MSGL0 to $MSGL1) } HULMSGS;- DWORD msgcnt
-
Number of messages that are stored
If you do not use long messages, specify '6.'
If you use long messages, specify '8.'
- CHAR** msginfo
-
This parameter specifies messages.
For each message, you can specify up to 50 bytes at maximum. Be sure to allocate a fixed-size array that is calculated by the formula 'Number of messages (6) x (maximum length 50 bytes + 1).' Specify each message every 51 bytes from the top. When the function ends, release the memory.
- CHAR** exmsginfo
-
This parameter specifies long messages.
Specify this parameter when you use long messages.
Each long message can be specified up to a maximum of 200 bytes. Be sure to allocate a fixed-size array that is calculated by the formula 'Number of long messages (2) x (maximum length 200 bytes +1).' Specify each long message every 201 bytes from the top. When the function ends, release the memory.
- INT nTransMode (IN)
-
Specify the transfer mode
Specify '0' as a fixed value.
Returned Value
This function returns '0' if the processing completes successfully. The status when an error occurs is the same as the error code of 'utlsend.exe.'
For details, refer to the following:
HULFT10 for Windows Error Codes and Messages : Send File command (utlsend.exe)
Usage example
Specifying settings when using Visual C++ (when long messages are not used)
#include <windows.h>
#include <stdio.h>
#pragma pack(push,8)
typedef struct {
DWORD msgcnt;
CHAR** msginfo;
} HULMSGS;
#pragma pack(pop)
typedef INT (__stdcall *LPUTLSENDEX)(
LPCSTR lpszFileID, LPCSTR lpszHostName, BOOL bResend,
SHORT nPriority, BOOL bSync, INT nWait, LPCSTR lpszFileName,
LPCSTR lpszGroup, BOOL bNp,
HULMSGS* lpMsg, INT nTransMode);
int main()
{
CHAR szFileID[50+1];
CHAR szHostName[68+1];
SHORT nPriority;
BOOL bResend;
BOOL bSync;
INT nWait;
CHAR szFileName[200+1];
CHAR szGroup[50+1];
BOOL bNp;
HULMSGS sMsgInfo;
CHAR* msgbodyptr[6];
CHAR msgbody[(50+1)*6];
INT nTransMode;
INT i;
HMODULE hHulDll;
HMODULE hApiDll;
LPUTLSENDEX lpUtlsendex;
INT nStatus;
strcpy_s(szFileID, sizeof(szFileID), "TEST0001");
strcpy_s(szHostName, sizeof(szHostName), "");
bResend = FALSE;
nPriority = 50;
bSync = TRUE;
nWait = 300;
strcpy_s(szFileName, sizeof(szFileName), "");
strcpy_s(szGroup, sizeof(szGroup), "");
bNp = FALSE;
nTransMode = 0;
sMsgInfo.msgcnt = 6;
sMsgInfo.msginfo = msgbodyptr;
for (i = 0; i < 6; i++)
{
sMsgInfo.msginfo[i] = &msgbody[51*i];
}
strcpy_s(sMsgInfo.msginfo[0], 51, "C:\\hulft\\");
strcpy_s(sMsgInfo.msginfo[1], 51, "");
strcpy_s(sMsgInfo.msginfo[2], 51, "");
strcpy_s(sMsgInfo.msginfo[3], 51, "Data1.dat");
strcpy_s(sMsgInfo.msginfo[4], 51, "");
strcpy_s(sMsgInfo.msginfo[5], 51, "");
hApiDll = LoadLibraryEx("C:\\HULFT Family\\hulft10\\bin\\hulapi.dll", NULL,
LOAD_WITH_ALTERED_SEARCH_PATH);
if (hApiDll == NULL)
{
printf("Unable to load hulapi.dll."
"(Error code = %lu)\n", GetLastError());
FreeLibrary(hHulDll);
return 2;
}
lpUtlsendex = (LPUTLSENDEX)GetProcAddress(hApiDll, "utlsendex");
if (lpUtlsendex == NULL)
{
printf("Unable to retrieves the address of HULFT API."
"(Error code=%lu)\n", GetLastError());
FreeLibrary(hApiDll);
FreeLibrary(hHulDll);
return 3;
}
nStatus = lpUtlsendex(szFileID, szHostName, bResend, nPriority,
bSync, nWait, szFileName, szGroup, bNp,
&sMsgInfo, nTransMode);
if (nStatus == 0)
{
printf("Terminated normally.\n");
}
else
{
printf("Error occurred when calling HULFT API."
"(Returned value=%d)\n", nStatus);
}
FreeLibrary(hApiDll);
FreeLibrary(hHulDll);
return 0;
}
Specifying settings when using Visual C++ (when long messages are used)
#include <windows.h>
#include <stdio.h>
#pragma pack(push,8)
typedef struct {
DWORD msgcnt;
CHAR** msginfo;
CHAR** exmsginfo;
} HULMSGS;
#pragma pack(pop)
typedef INT (__stdcall *LPUTLSENDEX)(
LPCSTR lpszFileID, LPCSTR lpszHostName, BOOL bResend,
SHORT nPriority, BOOL bSync, INT nWait, LPCSTR lpszFileName,
LPCSTR lpszGroup, BOOL bNp,
HULMSGS* lpMsg, INT nTransMode);
int main()
{
CHAR szFileID[50+1];
CHAR szHostName[68+1];
SHORT nPriority;
BOOL bResend;
BOOL bSync;
INT nWait;
CHAR szFileName[200+1];
CHAR szGroup[50+1];
BOOL bNp;
HULMSGS sMsgInfo;
CHAR* msgbodyptr[6];
CHAR msgbody[(50+1)*6];
CHAR* exmsgbodyptr[2];
CHAR exmsgbody[(200+1)*2];
INT nTransMode;
INT i;
HMODULE hHulDll;
HMODULE hApiDll;
LPUTLSENDEX lpUtlsendex;
INT nStatus;
strcpy_s(szFileID, sizeof(szFileID), "TEST0001");
strcpy_s(szHostName, sizeof(szHostName), "");
bResend = FALSE;
nPriority = 50;
bSync = TRUE;
nWait = 300;
strcpy_s(szFileName, sizeof(szFileName), "");
strcpy_s(szGroup, sizeof(szGroup), "");
bNp = FALSE;
nTransMode = 0;
sMsgInfo.msgcnt = 8;
sMsgInfo.msginfo = msgbodyptr;
for (i = 0; i < 6; i++)
{
sMsgInfo.msginfo[i] = &msgbody[51*i];
}
strcpy_s(sMsgInfo.msginfo[0], 51, "C:\\hulft\\");
strcpy_s(sMsgInfo.msginfo[1], 51, "");
strcpy_s(sMsgInfo.msginfo[2], 51, "");
strcpy_s(sMsgInfo.msginfo[3], 51, "Data1.dat");
strcpy_s(sMsgInfo.msginfo[4], 51, "");
strcpy_s(sMsgInfo.msginfo[5], 51, "");
sMsgInfo.exmsginfo = exmsgbodyptr;
for (i = 0; i < 2; i++)
{
sMsgInfo.exmsginfo[i] = &exmsgbody[201*i];
}
strcpy_s(sMsgInfo.exmsginfo[0], 201, "Data2.dat");
strcpy_s(sMsgInfo.exmsginfo[1], 201, "");
hApiDll = LoadLibraryEx("C:\\HULFT Family\\hulft10\\bin\\hulapi.dll", NULL, LOAD_WITH_ALTERED_SEARCH_PATH);
if (hApiDll == NULL)
{
printf("Unable to load hulapi.dll."
"(Error code = %lu)\n", GetLastError());
FreeLibrary(hHulDll);
return 2;
}
lpUtlsendex = (LPUTLSENDEX)GetProcAddress(hApiDll, "utlsendex");
if (lpUtlsendex == NULL)
{
printf("Unable to retrieves the address of HULFT API."
"(Error code=%lu)\n", GetLastError());
FreeLibrary(hApiDll);
FreeLibrary(hHulDll);
return 3;
}
nStatus = lpUtlsendex(szFileID, szHostName, bResend, nPriority,
bSync, nWait, szFileName, szGroup, bNp,
&sMsgInfo, nTransMode);
if (nStatus == 0)
{
printf("Terminated normally.\n");
}
else
{
printf("Error occurred when calling HULFT API."
"(Returned value=%d)\n", nStatus);
}
FreeLibrary(hApiDll);
FreeLibrary(hHulDll);
return 0;
}