Personal Communications provides an API set, which is defined here and called PCSAPI. Whereas EHLLAPI is used to manage the interaction between a workstation application program and host systems after the session is established, the PCSAPI can be used to control the Personal Communications session itself.
You can write application programs using the PCSAPI in C or C++. To develop a PCSAPI application, do the following:
You must also link it with the PCSAPI import library, PCSCALLS.LIB for 16-bit and PCSCAL32.LIB for 32-bit.
All PCSAPI function calls are presented in the same format so that you can quickly retrieve the information you need. The format is:
"Function Type" shows the type of the function in the following format:
TYPE FunctionName(TYPE Parameter1, ...)
"Parameter Type and Description" lists the type and describes each of the parameters to be specified in the PCSAPI function call.
"Return Code" lists the codes that must be received by your program after a call to the PCSAPI function.
3270 | 5250 | VT |
---|---|---|
Yes | Yes | Yes |
The pcsConnectSession function starts the communications with a host session specified by the short session ID. The session must already be started. This call is equivalent to the Communications -> Connect menu item on the emulator session panel.
BOOL WINAPI pcsConnectSession(char cShortSessionID)
Return Code | Meaning |
---|---|
TRUE | Function ended successfully. |
FALSE | It means one of the following things:
|
3270 | 5250 | VT |
---|---|---|
Yes | Yes | Yes |
The pcsDisconnectSession function stops the communications link with a host session specified by the short session ID. This only disconnects the link; it does not stop the session. This call is equivalent to the Communications -> Disconnect menu item on the emulator session panel.
BOOL WINAPI pcsDisconnectSession(char cShortSessionID)
Return Code | Meaning |
---|---|
TRUE | Function ended successfully. |
FALSE | It means one of the following things:
|
3270 | 5250 | VT |
---|---|---|
Yes | No | No |
The pcsQueryConnectionInfo function returns information about the Telnet connection of the specified host session. The resulting information is returned into the buffer supplied by the application.
BOOL WINAPI pcsQueryConnectionInfo(char cShortSessionID, CONNECTIONINFO *ConnectionInfo)
Return Code | Meaning |
---|---|
TRUE | Function ended successfully. |
FALSE | It means one of the following things:
|
The CONNECTIONINFO structure will be filled with the information about the host connection, consisting of the following information:
Structure | Information |
---|---|
Host name | States the name of the currently connected Telnet host. |
LU name | States the LU name currently assigned. |
Port number | States the host port number being used for the connection. |
SSL indicator | Indicates a Secure Connection (1 = secure; 0 = not secure). |
typedef struct_CONNECTIONINFO
{ //Description of a connection @WD06A
char hostName[63]; //telnet host name @WD06A
char reserved[1]; //reserved @wD06A
int portNumber; //host port number @WD06A
char luName[17]; //LU name @WD06A
char reserved2[3]; //reserved @WD06A
BOOL sslIndicator; //Secure Connection @WD06A
indicator
char reserved3[256]; //reserved @WD06A
}CONNECTIONINFO;
3270 | 5250 | VT |
---|---|---|
Yes | Yes | Yes |
The pcsQueryEmulatorStatus function returns the status of the host session specified by the short session ID.
ULONG WINAPI pcsQueryEmulatorStatus(char cShortSessionID)
The return code value should be processed bit-significantly, that is, by either one of the following values or an ORed value out of the following values:
Return Code | Value | Meaning |
---|---|---|
PCS_SESSION_STARTED | 0x00000001 | Specified session has started. When this bit is off, the specified session has not started or an incorrect session ID was specified. |
PCS_SESSION_ONLINE | 0x00000002 | Specified session is online (connected). When this bit is off, the specified session is offline (disconnected). |
PCS_SESSION_API_ENABLED | 0x00000004 | API (EHLLAPI, DDE) is enabled on the specified session. If this bit is off, API is disabled on this session. |
3270 | 5250 | VT |
---|---|---|
Yes | Yes | Yes |
The pcsQuerySessionList function returns a list of all the current host sessions. The application must supply an array of SESSINFO structures as defined in the PCSAPI.H file, and a count of the number of elements in the array. This function fills in the structures with information about each session and returns the number of sessions found.
If the array has fewer elements than there are host sessions, then only the supplied elements of the array are filled in. The function always returns the actual number of sessions, even if the array is too small.
An application can call this function with zero array elements to determine how many sessions exist. A second call can then be made to obtain the session information.
ULONG WINAPI pcsQuerySessionList(ULONG Count, SESSINFO *SessionList)
The status value should be processed bit-significantly, that is, by either one of the following values or an ORed value out of the following values:
Return Code | Meaning |
---|---|
PCS_SESSION_STARTED | The session is running. If this flag is not set, all others are undefined. |
PCS_SESSION_ONLINE | The session has established a communications link to the host (this is, the session is connected). |
PCS_SESSION_API_ENABLED | The session is enabled for programming APIs. If this flag is not set, the EHLLAPI and Host Access Class Library APIs cannot be used on this session. |
ULONG NumSessions, i; // Session counters
SESSINFO *SessList; // Array of session information structures
// Find out number of sessions that exist
NumSessions = pcsQuerySessionList (0,NULL);
if (NumSessions == 0) {
printf("There are no sessions.");
exit;
}
// Allocate array large enough for all sessions
SessList = (SESSINFO *)malloc(NumSessions * sizeof(SESSINFO));
memset(SessList, 0x00, NumSessions * sizeof(SESSINFO));
// Now read actual session info
pcsQuerySessionList(NumSessions, SessList);
for (i=0; i<NumSessions; i++) {
if ((SessList[i].Status & PCS_SESSION_STARTED) &&
(SessList[i].Status & PCS_SESSION_ONLINE)) {
printf("Session %c is started and connected.",
SessList[i].Name.ShortName);
}
}
exit;
3270 | 5250 | VT |
---|---|---|
Yes | Yes | Yes |
The pcsQueryWorkstationProfile function returns the workstation profile name that has been used to invoke the host session. To specify the host session, the short session ID must be used. The workstation profile name is copied to the work buffer supplied by the application.
BOOL WINAPI pcsQueryWorkstationProfile(char cShortSessionID, PSZ lpBuffer)
Return Code | Meaning |
---|---|
TRUE | Function ended successfully. |
FALSE | It means one of the following things:
|
3270 | 5250 | VT |
---|---|---|
Yes | Yes | Yes |
The pcsSetLinkTimeout function sets the idle timeout of a Telnet link which is SSCP owned. This function has no effect on non-TN connections or connections which are not in SSCP owned state. If the timeout value is set to zero the link will not time out. Otherwise the link will time out (disconnect) after being idle in SSCP-owned state for the number of minutes specified.
ULONG WINAPI pcsSetLinkTimeout(char cShortSessionID, USHORT Timeout)
Return Code | Meaning |
---|---|
PCS_SUCCESSFUL | The function ended successfully. |
PCS_SYSTEM_ERROR | A system error occurred. |
3270 | 5250 | VT |
---|---|---|
Yes | Yes | Yes |
The pcsStartSession function starts a host session by using a specified workstation profile. A short session ID can also be specified.
ULONG WINAPI pcsStartSession(PSZ lpProfile, char cShortSessionID, USHORT fuCmdShow)
Return Code | Value | Meaning |
---|---|---|
PCS_SUCCESSFUL | 0 | The function ended successfully. |
PCS_INVALID_ID | 1 | An incorrect session ID was specified. |
PCS_USED_ID | 2 | The specified short session ID is already used. |
PCS_INVALID_PROFILE | 3 | An error was made in specifying the workstation profile, or the window parameter was not valid. |
PCS_SYSTEM_ERROR | 9 | A system error occurred. |
3270 | 5250 | VT |
---|---|---|
Yes | Yes | Yes |
The pcsStopSession function stops a host session specified by the short session ID.
BOOL WINAPI pcsStopSession(char cShortSessionID, USHORT fuSaveProfile)
fuSaveProfile | Value | Meaning |
---|---|---|
PCS_SAVE_AS_PROFILE | 0 | Save the profile as specified in the current profile. |
PCS_SAVE_ON_EXIT | 1 | Save the profile on exit. |
PCS_NOSAVE_ON_EXIT | 2 | Do not save the profile on exit. |
Return Code | Meaning |
---|---|
TRUE | The function ended successfully. |
FALSE | It means one of the following things:
|
The PCSAPI functions listed in this section enable you to control and retrieve the Personal Communications emulator session Page Setup settings.
If the following restrictions are not satisfied, the API will fail. The return code indicates the reason for the failure.
Some members in the PAGEINFO structure might be valid or supported only for specific session types. If a restriction is not specified, then that member is valid or supported for the following session types:
5250 printer sessions are not supported.
3270 | 5250 | VT |
---|---|---|
Yes | Yes | Yes |
The pcsGetPageSettings function retrieves the host session page settings values (similar to the File -> Page Setup dialog settings). Only the settings in the Text tab of the dialog are supported.
ULONG WINAPI pcsGetPageSettings(char cShortSessionID, PAGEINFO * const pPageInfo, ULONG * const pErrorInfo)
LOWORD is the actual CPI value.
If Font CPI is configured in the session, HIWORD is 1. If Font CPI is not configured, HIWORD is 0.
LOWORD is the actual LPI value.
If Font LPI is configured in the session, HIWORD is 1. If Font LPI is not configured, HIWORD is 0.
This is also called MPL (Maximum Print Lines). Supported range is 1 to 255.
This is also called MPP (Maximum Print Position). Supported range is 1 to 255.
Return Code | Value | Meaning |
---|---|---|
PCS_SUCCESSFUL | 0 | Function ended successfully. |
PCS_INVALID_ID | 1 | Incorrect session ID was specified. |
PCS_INVALID_SESS_TYPE | 2 | Not supported for the host session type. |
PCS_DIALOG_IN_USE | 3 | Failed because the host session Page Setup or Printer Setup dialog was in use. |
PCS_PRINTING | 4 | Page settings cannot be obtained because host session was printing. |
PCS_PDT_MODE | 5 | Page settings cannot be obtained because host session is in PDT mode. |
PCS_SYSTEM_ERROR | 9 | A system error occurred. |
{
ULONG Rc = 0;
PAGEINFO *PageInfo;
PageInfo = (PAGEINFO *) malloc(sizeof(PAGEINFO));
memset(PageInfo, 0, sizeof(PAGEINFO));
PageInfo->nFlags = PCS_PAGE_CPI | PCS_PAGE_LPI | PCS_PAGE_FACE_NAME|
PCS_PAGE_MPL | PCS_PAGE_MPP;
Rc = pcsGetPageSettings('A', PageInfo, NULL);
if (Rc == PCS_SUCCESSFUL) {
printf("CPI = %d,
LPI = %d,
FaceName = %s,
MPL = %d,
MPP = %d\n",
LOWORD(PageInfo->nCPI),
LOWORD(PageInfo->nLPI),
PageInfo->szFaceName,
PageInfo->nMPL,
PageInfo->nMPP);
if (HIWORD(PageInfo->nCPI))
printf("FontCPI\n");
else
printf("No FontCPI\n");
if (HIWORD(PageInfo->nLPI))
printf("FontLPI\n");
else
printf("No FontLPI\n");
} else
printf("Failure. Return code = %d\n", Rc);
free(PageInfo);
}
3270 | 5250 | VT |
---|---|---|
Yes | Yes | Yes |
The pcsRestorePageDefaults function restores the system default values of the Page Setup property pages defined in the nFlags field. This is equivalent to clicking Default in the property pages of the File -> Page Setup dialog. Only the settings in the Text tab are supported.
ULONG WINAPI pcsRestorePageDefaults(char cShortSessionID, ULONG nFlags)
Return Code | Value | Meaning |
---|---|---|
PCS_SUCCESSFUL | 0 | Function ended successfully. |
PCS_INVALID_ID | 1 | Incorrect session ID was specified. |
PCS_INVALID_SESS_TYPE | 2 | The nFlags parameter has one or more options that are not valid for the host session type. No settings were restored. |
PCS_DIALOG_IN_USE | 3 | Failed because the host session Page Setup or Printer Setup dialog was in use. |
PCS_PRINTING | 4 | Page settings cannot be changed because host session was printing. |
PCS_PDT_MODE | 5 | Page settings cannot be changed because host session is in PDT mode. |
PCS_SYSTEM_ERROR | 9 | A system error occurred. |
{
ULONG Rc = 0;
Rc = pcsRestorePageDefaults('A', PCS_PAGE_TEXT);
if (Rc != PCS_SUCCESSFUL)
printf("Failure. Return code = %d\n", Rc);
}
3270 | 5250 | VT |
---|---|---|
Yes | Yes | Yes |
The pcsSetPageSettings function sets the host session page settings. This is similar to configuring the File -> Page Setup dialog settings. Only the settings in the Text tab are supported.
ULONG WINAPI pcsSetPageSettings(char cShortSessionID, const PAGEINFO * const pPageInfo, ULONG * const pErrorInfo)
To select Font CPI, set the HIWORD of nCPI to 1. LOWORD of nCPI will be ignored.
To select a particular CPI value, do the following:
To select Font LPI, set the HIWORD of nLPI to 1. LOWORD of nLPI will be ignored
To select a particular LPI value, do the following:
This is also called MPL (Maximum Print Lines). Supported range is 1 to 255.
This is also called MPP (Maximum Print Position). Supported range is 1 to 255.
This is a combination of bit flags that describe which members of the PAGEINFO structure could not be set successfully. The flags that are defined in PCSAPI32.H are as follows:
Return Code | Value | Meaning |
---|---|---|
PCS_SUCCESSFUL | 0 | Function ended successfully. |
PCS_INVALID_ID | 1 | Incorrect session ID was specified. |
PCS_INVALID_SESS_TYPE | 2 | Not supported for the host session type. |
PCS_DIALOG_IN_USE | 3 | Failed because the host session Page Setup or Printer Setup dialog was in use. |
PCS_PRINTING | 4 | Page settings cannot be changed because host session was printing. |
PCS_PDT_MODE | 5 | Page settings cannot be changed because host session is in PDT mode. |
PCS_FAILURE | 6 | Host session page settings are not fully applied.
This could be because invalid data was given for some or all fields
in the PAGEINFO structure.
Examine pErrorInfo for details about settings that are not applied. |
PCS_SYSTEM_ERROR | 9 | A system error occurred. |
{
ULONG Rc = 0, Error = 0;
PAGEINFO *PageInfo;
PageInfo = (PAGEINFO *) malloc(sizeof(PAGEINFO));
memset(PageInfo, 0, sizeof(PAGEINFO));
PageInfo->nFlags = PCS_PAGE_CPI | PCS_PAGE_LPI |
PCS_PAGE_FACE_NAME| PCS_PAGE_MPL |
PCS_PAGE_MPP;
PageInfo->nCPI = MAKELONG(10, 0);
PageInfo->nLPI = MAKELONG(8, 0);
PageInfo->nMPL = 40;
PageInfo->nMPP = 60;
strcpy(PageInfo->szFaceName, "CourierPS");
Rc = pcsSetPageSettings('A', PageInfo, &Error);
if (Rc != PCS_SUCCESSFUL) {
printf("Failure. Return code = %d\n", Rc);
printf("Following members could not be set : ");
if (Rc == PCS_FAILURE) {
if (Error & PCS_PAGE_CPI) printf(" nCPI");
if (Error & PCS_PAGE_LPI) printf(" nLPI");
if (Error & PCS_PAGE_FACE_NAME) printf(" szFaceName");
if (Error & PCS_PAGE_MPL) printf(" nMPL");
if (Error & PCS_PAGE_MPP) printf(" nMPP");
printf("\n");
}
}
free(PageInfo);
}
The PCSAPI functions listed in this section enable you to control and retrieve the Personal Communications emulator session Printer Setup settings.
If the following restrictions are not met, the API will fail. The return code indicates the reason for the failure.
3270 | 5250 | VT |
---|---|---|
Yes | Yes | Yes |
The pcsGetPrinterSettings function retrieves the host session printer settings (similar to the File -> Printer Setup dialog settings).
ULONG WINAPI pcsGetPrinterSettings(char cShortSessionID, PRINTINFO * const pPrintInfo, ULONG * const pErrorInfo)
If this member is set to 0, the fields are ignored. The maximum size required for the buffers of the fields is returned in nSizeNeeded.
When the API returns, this member contains one of the following:
This is equivalent to selecting the Append option in the host session Printer Setup -> Printer -> Print to Disk dialog.
This is equivalent to selecting the Separate option in the host session Printer Setup -> Printer -> Print to Disk dialog.
This is equivalent to selecting the Use Windows Default Printer option in the host session Printer Setup dialog.
This is equivalent to selecting a printer in the host session Printer Setup dialog, while leaving Use Windows Default Printer unchecked.
When the API returns, this member contains one of the following:
When the API returns, this member contains one of the following:
When the API returns, this member has one of the following:
PrinterName must have the following format:
<Printer name> on <Port Name>
For example:
The following section describes the flags that are defined in PCSAPI32.H.
Return Code | Value | Meaning |
---|---|---|
PCS_SUCCESSFUL | 0 | The function ended successfully. |
PCS_INVALID_ID | 1 | An incorrect session ID was specified. |
PCS_DIALOG_IN_USE | 3 | Failed because the host session Page Setup or Printer Setup dialog was in use. |
PCS_PRINTING | 4 | The printer settings could not be changed because the host session was printing. The application must retry later |
PCS_FAILURE | 6 | Some printer settings could not be retrieved successfully. pErrorInfo contains detailed error information on which settings could not be retrieved. |
PCS_SYSTEM_ERROR | 9 | A system error occurred. |
{
ULONG Rc = 0, Error=0, Size;
PRINTINFO *PrintInfo;
PrintInfo = (PRINTINFO *) malloc(sizeof(PRINTINFO));
memset(PrintInfo, 0, sizeof(PRINTINFO));
PrintInfo->nBufSize = 0;
Rc = pcsGetPrinterSettings('A', PrintInfo, &Error);
if (Rc != PCS_SUCCESSFUL)
printf("Failure. Return code = %d\n", Rc);
else {
Size = PrintInfo->nSizeNeeded;
PrintInfo->nBufSize = Size;
PrintInfo->lpPDTFile = (char *)malloc(sizeof(char) * Size);
PrintInfo->lpPrtToDskAppFile = (char *)malloc(sizeof(char) * Size);
PrintInfo->lpPrtToDskSepFile = (char *)malloc(sizeof(char) * Size);
PrintInfo->lpPrinterName = (char *)malloc(sizeof(char) * Size);
Rc = pcsGetPrinterSettings('A', PrintInfo, &Error);
if (Rc != PCS_SUCCESSFUL)
printf("Failure. Return code = %d, Extended Error = 0x%08x\n", Rc, Error);
else {
if (PrintInfo->bPromptDialog)
printf("PromptDialog\n");
else
printf("No PromptDialog\n");
if (PrintInfo->bPDTMode)
printf("PDT Mode\n");
else
printf("Not PDT Mode\n");
switch(PrintInfo->nPrtMode) {
case PrtToDskAppend:
printf("Print to Disk-Append Mode\n");
break;
case PrtToDskSeparate:
printf("Print to Disk-Separate Mode\n");
break;
case SpecificPrinter:
printf("Specific Printer Mode\n");
break;
case WinDefaultPrinter:
printf("Windows Default Printer Mode\n");
break;
}
if (PrintInfo->lpPDTFile[0] == '\0')
printf("No PDT File configured\n");
else
printf("PDT File = %s\n", PrintInfo->lpPDTFile);
if (PrintInfo->lpPrtToDskAppFile[0] == '\0')
printf("No Disk Append File configured\n");
else
printf("DiskAppend File=%s\n", PrintInfo->lpPrtToDskAppFile);
if (PrintInfo->lpPrtToDskSepFile[0] == '\0')
printf("No Disk Separate File configured\n");
else
printf("DiskSeparate File=%s\n", PrintInfo->lpPrtToDskSepFile);
if ((PrintInfo->nPrtMode == SpecificPrinter) ||
(PrintInfo->nPrtMode == WinDefaultPrinter))
printf("Printer = %s\n", PrintInfo->lpPrinterName);
}
free(PrintInfo->lpPDTFile);
free(PrintInfo->lpPrtToDskAppFile);
free(PrintInfo->lpPrtToDskSepFile);
free(PrintInfo->lpPrinterName);
}
free(PrintInfo);
}
3270 | 5250 | VT |
---|---|---|
Yes | Yes | Yes |
The pcsSetPrinterSettings function controls the host session printer settings (similar to the File -> Printer Setup dialog settings).
ULONG WINAPI pcsSetPrinterSettings(char cShortSessionID, const PRINTINFO * const pPrintInfo, ULONG * const pErrorInfo)
This is a null-terminated string containing the name of the PDT file and must be one of the following:
The PDT file that is currently configured in the connection is used. If there is no PDT file already configured in the connection, the API fails with an exception.
lpPDTFile in the PDFPDT subfolder in the Personal Communications installation path is used.
If lpPDTFile does not exist, the API fails.
This is equivalent to selecting the Append option in the host session Printer Setup -> Printer -> Print to Disk dialog.
This is equivalent to selecting the Separate option in the host session Printer Setup -> Printer -> Print to Disk dialog.
This is equivalent to selecting the Use Windows Default Printer option in the host session Printer Setup dialog.
This is equivalent to selecting a printer in the host session Printer Setup dialog, while leaving the Use Windows Default Printer option unchecked.
This is a null-terminated string containing the name of the Print to Disk-Append file and must be one of the following:
The file that is currently configured for the PrtToDskAppend mode in the connection is used. If there is no PDT file already configured in the connection, the API will fail.
The user-class application data directory path is used to locate the file. If the file exists, it is used. Otherwise, it will be created when printing is complete.
The directory must exist in the path, or the API will fail. It is not necessary that the file exist in the path.
PrinterName must have the following format:
<Printer name> on <Port Name>
For example:
The following section describes the flags that are defined in PCSAPI32.H.
Return Code | Value | Meaning |
---|---|---|
PCS_SUCCESSFUL | 0 | The function ended successfully. |
PCS_INVALID_ID | 1 | An incorrect session ID was specified. |
PCS_DIALOG_IN_USE | 3 | Failed because the host session Page Setup or Printer Setup dialog was in use. |
PCS_PRINTING | 4 | The printer settings could not be changed because the host session was printing. The application must retry later. |
PCS_FAILURE | 6 | No host session printer settings were applied. This might occur because invalid data was given for some or all of the fields in the PRINTINFO structure. pErrorInfo contains details about the errors. |
PCS_SYSTEM_ERROR | 9 | A system error occurred. |
{
ULONG Rc = 0, Error=0;
PRINTINFO *PrintInfo;
char PDTFile[] = "epson.pdt";
char SepFile[] = "DiskSep";
PrintInfo = (PRINTINFO *) malloc(sizeof(PRINTINFO));
memset(PrintInfo, 0, sizeof(PRINTINFO));
PrintInfo->nFlags = PCS_PRINT_PDT | PCS_PRINT_PRINTMODE |
PCS_PRINT_PROMPT_DIALOG;
PrintInfo->nBufSize = 0;
PrintInfo->nSizeNeeded = 0;
PrintInfo->bPDTMode = TRUE;
PrintInfo->lpPDTFile =
(char *)malloc(sizeof(char) * (strlen(PDTFile)+1));
strcpy(PrintInfo->lpPDTFile, PDTFile);
PrintInfo->nPrtMode = PrtToDskSeparate;
PrintInfo->lpPrtToDskSepFile =
(char *)malloc(sizeof(char) * (strlen(SepFile)+1));
strcpy(PrintInfo->lpPrtToDskSepFile, SepFile);
PrintInfo->bPromptDialog = TRUE;
Rc = pcsSetPrinterSettings('A', PrintInfo, &Error);
if (Rc != PCS_SUCCESSFUL)
printf("Failure. Return code = %d, Extended Error = 0x%08x\n", Rc, Error);
free(PrintInfo->lpPDTFile);
free(PrintInfo->lpPrtToDskSepFile);
free(PrintInfo);
}