PCSAPI Functions

Z and I Emulator for Windows 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 Z and I Emulator for Windows session itself.

How to Use PCSAPI

You can write application programs using the PCSAPI in C or C++. To develop a PCSAPI application, do the following:

  1. Prepare source code and add the appropriate PCSAPI calls.
  2. Include the header file PCSAPI.H in the application program.
  3. Compile the source code.
  4. Link the resultant .OBJ files with the appropriate object file or libraries.

    You must also link it with the PCSAPI import library, PCSCALLS.LIB for 16-bit and PCSCAL32.LIB for 32-bit.

Page Layout Conventions

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

"Function Type" shows the type of the function in the following format:

TYPE FunctionName(TYPE Parameter1, ...)

Parameter Type and Description

"Parameter Type and Description" lists the type and describes each of the parameters to be specified in the PCSAPI function call.

Return Code

"Return Code" lists the codes that must be received by your program after a call to the PCSAPI function.

pcsConnectSession

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.

Function Type

BOOL WINAPI pcsConnectSession(char cShortSessionID)

Parameter Type and Description

char cShortSessionID
Presentation space short session ID.

Return Code

Return Code Meaning
TRUE Function ended successfully.
FALSE It means one of the following things:
  • The session has not started.
  • An incorrect session ID was specified.
  • Call failed.

pcsDisconnectSession

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.

Function Type

BOOL WINAPI pcsDisconnectSession(char cShortSessionID)

Parameter Type and Description

char cShortSessionID
Presentation space short session ID.

Return Code

Return Code Meaning
TRUE Function ended successfully.
FALSE It means one of the following things:
  • The session has not started.
  • An incorrect session ID was specified.
  • Call failed.

pcsQueryConnectionInfo

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.

Function Type

BOOL WINAPI pcsQueryConnectionInfo(char cShortSessionID, CONNECTIONINFO *ConnectionInfo)

Parameter Type and Description

char cShortSessionID
Presentation space short session ID.
CONNECTIONINFO *ConnectionInfo
Pointer to a CONNECTIONINFO structure where the connection info data will be returned.

Return Code

Return Code Meaning
TRUE Function ended successfully.
FALSE It means one of the following things:
  • The session has not started.
  • An incorrect session ID was specified.
  • The session specified was not a supported connection type for this API (not Telnet).

ConnectionInfo

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).
Note:
This API is valid only with the 32-bit version of PCSAPI, and only works for Telnet connections.

Example

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;

pcsQueryEmulatorStatus

3270 5250 VT
Yes Yes Yes

The pcsQueryEmulatorStatus function returns the status of the host session specified by the short session ID.

Function Type

ULONG WINAPI pcsQueryEmulatorStatus(char cShortSessionID)

Parameter Type and Description

char cShortSessionID
Presentation space short session ID.

Return Code

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) is enabled on the specified session. If this bit is off, API is disabled on this session.

pcsQuerySessionList

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.

Function Type

ULONG WINAPI pcsQuerySessionList(ULONG Count, SESSINFO *SessionList)

Parameter Type and Description

ULONG Count
Number of elements in the SessionList array.
SESSINFO *SessionList
Pointer to an array of SESSINFO structures as defined in PCSAPI.H.

Return Parameters

Return Code
Total number of Z and I Emulator for Windows sessions. This may be greater than or less than the Count parameter.
SessionList
The array of SESSINFO structures is filled with information about the host sessions. Sessions may be placed in the list in any order. Each SESSINFO structure contains the following fields (defined in PCSAPI32.H)
Name
A union of char and ULONG which contains the session ID (A-Z). In the current implementation of Z and I Emulator for Windows, only the lower byte (char) is used, the other bytes are returned as zero.
Status
A combination of bit flags which indicate the current status of the session. The flags (PCS_SESSION_*) are defined in the following table.

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.

Example

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;  

pcsQueryWorkstationProfile

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.

Function Type

BOOL WINAPI pcsQueryWorkstationProfile(char cShortSessionID, PSZ lpBuffer)

Parameter Type and Description

char cShortSessionID
Presentation space short session ID.
PSZ lpBuffer
Work buffer to copy a null-terminated workstation profile name. The buffer must be large enough to contain a fully qualified file name.

Return Code

Return Code Meaning
TRUE Function ended successfully.
FALSE It means one of the following things:
  • The session has not started.
  • An incorrect session ID was specified.

pcsSetLinkTimeout

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.

Function Prototype

ULONG WINAPI pcsSetLinkTimeout(char cShortSessionID, USHORT Timeout)

Parameter Type and Description

char cShortSessionID
Presentation space short session ID.
USHORT Timeout
Timeout value in minutes. A value of zero disables timeout.

Return Code

Return Code Meaning
PCS_SUCCESSFUL The function ended successfully.
PCS_SYSTEM_ERROR A system error occurred.

pcsStartSession

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.

Function Type

ULONG WINAPI pcsStartSession(PSZ lpProfile, char cShortSessionID, USHORT fuCmdShow)

Parameter Type and Description

PSZ lpProfile
Path and complete filename of the profile to load. Path is optional but complete filename must be specified (.ws extension is not assumed).
char cShortSessionID
Presentation space short session ID. Space or NULL indicates the next available session ID.
USHORT fuCmdShow
Specifies how the window is to be displayed. One of the following values from PCSAPI.H:

Return Code

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.

pcsStopSession

3270 5250 VT
Yes Yes Yes

The pcsStopSession function stops a host session specified by the short session ID.

Function Type

BOOL WINAPI pcsStopSession(char cShortSessionID, USHORT fuSaveProfile)

Parameter Type and Description

char cShortSessionID
Presentation space short session ID.
USHORT fuSaveProfile
This parameter can be one of the following values:
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

Return Code Meaning
TRUE The function ended successfully.
FALSE It means one of the following things:
  • The session has not started.
  • An incorrect session ID was specified.

Page Setup Functions

The PCSAPI functions listed in this section enable you to control and retrieve the Z and I Emulator for Windows emulator session Page Setup settings.

Restrictions

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.

pcsGetPageSettings

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.

Function Type

ULONG WINAPI pcsGetPageSettings(char cShortSessionID, PAGEINFO * const pPageInfo, ULONG * const pErrorInfo)

Parameter Type and Description

char cShortSessionID
Presentation space short session ID.
PAGEINFO * const pPageInfo
Pointer to PAGEINFO structure, where the page settings are returned.
nFlags
Combination of bit flags that indicates which members in the structure are valid. These flags can be used independently or by ORing them together to restore the property page (defined in PCSAPI32.H). The flags, along with the corresponding valid members in the structure, are as follows:
Flag
Valid members in the structure
PCS_PAGE_CPI
nCPI
PCS_PAGE_LPI
nLPI
PCS_PAGE_FACE_NAME
szFaceName
PCS_PAGE_MPL
nMPL
PCS_PAGE_MPP
nMPP
nCPI
The number of characters printed per inch.

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.

nLPI
The number of lines printed per inch.

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.

szFaceName
Face name of the printer font. This must be a null-terminated string.
nMPL
Maximum number of lines that can be printed per page.

This is also called MPL (Maximum Print Lines). Supported range is 1 to 255.

nMPP
Maximum number of characters that can be printed per line.

This is also called MPP (Maximum Print Position). Supported range is 1 to 255.

ULONG * const pErrorInfo
Not used. This must be set to NULL by the caller.

Return Code

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.

Example

{
   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);
}

pcsRestorePageDefaults

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.

Function Type

ULONG WINAPI pcsRestorePageDefaults(char cShortSessionID, ULONG nFlags)

Parameter Type and Description

char cShortSessionID
Presentation space short session ID.
ULONG nFlags
The following flag describes the name of the specified Page Setup dialog property page. This flag can be bitwise ORed to restore the property page (defined in PCSAPI32.H).
PCS_PAGE_TEXT
This flag describes the Text property page. This is the only property page currently supported.

Return Code

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.

Example

{ 
   ULONG Rc = 0; 

   Rc = pcsRestorePageDefaults('A', PCS_PAGE_TEXT); 

   if (Rc != PCS_SUCCESSFUL) 
      printf("Failure. Return code = %d\n", Rc); 
}

pcsSetPageSettings

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.

Notes:
  1. CPI, LPI, and FontSize are dependent on the FaceName configured in the host session. If this API is used to set CPI, LPI, FontSize, and FaceName together, FaceName is set first, then the dependent properties.
  2. If this API is used to set FaceName and the dependent properties in separate invocations, set FaceName first, then set CPI, LPI and FontSize. Otherwise, each time FaceName is set, query CPI, LPI and FontSize and ensure that they have the desired values.
  3. If CPI, LPI, or FontSize are set before FaceName, then different values for CPI, LPI, or FontSize might be configured in the host session. This might occur if the current CPI, LPI, or FontSize values are not valid for the new FaceName set.

Function Type

ULONG WINAPI pcsSetPageSettings(char cShortSessionID, const PAGEINFO * const pPageInfo, ULONG * const pErrorInfo)

Parameter Type and Description

char cShortSessionID
Presentation space short session ID.
const PAGEINFO * const pPageInfo
Pointer to PAGEINFO structure, where the page settings are mentioned.
nFlags
Combination of bit flags that indicates which members in the structure are valid. These flags can be used independently or by ORing them together to restore the property page (defined in PCSAPI32.H). The flags, along with the corresponding valid members in the structure, are as follows:
Flag
Valid members in the structure
PCS_PAGE_CPI
nCPI
PCS_PAGE_LPI
nLPI
PCS_PAGE_FACE_NAME
szFaceName
PCS_PAGE_MPL
nMPL
PCS_PAGE_MPP
nMPP
nCPI
The number of characters printed per inch.

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:

  1. Set the HIWORD of nCPI to 0.
  2. Set the LOWORD of nCPI to the actual CPI value.
nLPI
The number of lines printed per inch.

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:

  1. Set the HIWORD of nLPI to 0.
  2. Set the LOWORD of nLPI to the actual LPI value.
szFaceName
Face name of the printer font. This must be a null-terminated string.
nMPL
Maximum number of lines that can be printed per page.

This is also called MPL (Maximum Print Lines). Supported range is 1 to 255.

nMPP
Maximum number of characters that can be printed per line.

This is also called MPP (Maximum Print Position). Supported range is 1 to 255.

ULONG * const pErrorInfo
Contains the extended error info when the API fails with the return code of PCS_FAILURE. If the detailed error information is not needed, this flag must be set to NULL by the caller.

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:

Flag
Valid members in the structure
PCS_PAGE_CPI
Only nCPI is not valid.
PCS_PAGE_LPI
Only nLPI is not valid.
PCS_PAGE_FACE_NAME
Only szFaceName is not valid.
PCS_PAGE_MPL
Only nMPL is not valid.
PCS_PAGE_MPP
Only nMPP is not valid.

Return Code

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.

Example

{
   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);
}

Printer Setup Functions

The PCSAPI functions listed in this section enable you to control and retrieve the Z and I Emulator for Windows emulator session Printer Setup settings.

Restrictions

If the following restrictions are not met, the API will fail. The return code indicates the reason for the failure.

pcsGetPrinterSettings

3270 5250 VT
Yes Yes Yes

The pcsGetPrinterSettings function retrieves the host session printer settings (similar to the File -> Printer Setup dialog settings).

Function Type

ULONG WINAPI pcsGetPrinterSettings(char cShortSessionID, PRINTINFO * const pPrintInfo, ULONG * const pErrorInfo)

Parameter Type and Description

char cShortSessionID
Presentation space short session ID.
PRINTINFO * const pPrintInfo
Pointer to PRINTINFO structure, where the printer settings are specified.
nFlags
Must be set to 0. This is ignored.
nBufSize
Size of the buffer allocated for the following fields:
  • lpPDTFile
  • lpPrtToDskAppFile
  • lpPrtToDskSepFile
  • lpPrinterName
If more than one of these members is retrieved in a single API call, then the caller must allocate the same size for all the buffers and pass that size in this member.

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.

nSizeNeeded
The value of this member is determined by conditions related to the following fields:
  • lpPDTFile
  • lpPrtToDskAppFile
  • lpPrtToDskSepFile
  • lpPrinterName
The conditions are as follows:
  • The value is the number of bytes needed, if the size of the buffer allocated by the caller is not big enough to return the fields listed above.
  • The value is the maximum size of the required buffer, if more than one of the fields listed above are obtained by the caller.
  • If nBufSize is set to 0 by the caller, this member contains the maximum size required for the buffers of the fields listed above.
bPromptDialog
Possible values are as follows:
  • If TRUE, the Printer Setup dialog is shown before printing.
  • If FALSE, the Printer Setup dialog is not shown before printing.
bPDTMode
Possible values are as follows:
  • If TRUE, the host session is in PDT mode.
  • If FALSE, the host session is in non-PDT mode (GDI mode).
lpPDTFile
Must be set to NULL if the caller is not interested in getting this member. The PDT file is returned if this is not a null pointer. This must point to the buffer of size nBufSize allocated by the caller.

When the API returns, this member contains one of the following:

  • The fully qualified path name of the session PDT file.
  • An empty string ("") if no PDT file is configured in the session.
  • A truncated file name if the buffer size is not sufficient. The member nSizeNeeded contains the size of the buffer needed.
nPrtMode
This is an enumerated value that indicates the PrintMode of the connection. The enum data type PRINTMODE is defined in PCSAPI32.H. The nPrtMode setting must be one of the following:
  • PrtToDskAppend (Print to Disk-Append mode)

    This is equivalent to selecting the Append option in the host session Printer Setup -> Printer -> Print to Disk dialog.

  • PrtToDskSeparate (Print to Disk-Separate mode)

    This is equivalent to selecting the Separate option in the host session Printer Setup -> Printer -> Print to Disk dialog.

  • WinDefaultPrinter (Windows Default Printer mode)

    This is equivalent to selecting the Use Windows Default Printer option in the host session Printer Setup dialog.

  • SpecificPrinter (Specific Printer mode)

    This is equivalent to selecting a printer in the host session Printer Setup dialog, while leaving Use Windows Default Printer unchecked.

lpPrtToDskAppFile
Must be set to NULL if the caller is not interested in getting this member. The Print to Disk-Append file is returned if this is not a null pointer. This must point to the buffer of size nBufSize allocated by the caller.

When the API returns, this member contains one of the following:

  • The fully qualified path name of the session Print to Disk-Append file.
  • An empty string ("") if no Print to Disk-Append file is configured for the session.
  • A truncated file name if the buffer size is not sufficient. The nSizeNeeded member contains the size of the buffer needed.
lpPrtToDskSepFile
Must be set to NULL if the caller is not interested in getting this member. The Print to Disk-Separate file is returned if this is not a null pointer. This must point to the buffer of size nBufSize allocated by the caller.

When the API returns, this member contains one of the following:

  • The fully qualified path name of the session Print to Disk-Separate file.
  • An empty string ("") if no Print to Disk-Separate file is configured for the session.
  • A truncated file name if the buffer size is not sufficient. The nSizeNeeded member contains the size of the buffer needed.
lpPrinterName
Must be set to NULL if the caller is not interested in getting this member. The name of the printer is returned if this is not a null pointer. This must point to the buffer of size nBufSize allocated by the caller.

When the API returns, this member has one of the following:

  • The name of the specific printer configured in the session, if the host session nPrtMode is SpecificPrinter.
  • The name of the Windows default printer configured in the session, if the host session nPrtMode is WinDefaultPrinter.
  • An empty string (""), if the host session nPrtMode is PrtToDskAppend or PrtToDskSeparate.
  • A truncated printer name, if the buffer size is not sufficient. nSizeNeeded has the size of the buffer needed.

PrinterName must have the following format:

<Printer name> on <Port Name>

For example:

  • IBM InfoPrint 40 PS on Network Port
  • HP LaserJet 4050 Series PCL 6 on LPT1
ULONG * const pErrorInfo
This is filled with the extended error info when the API fails with the return code of PCS_FAILURE. pErrorInfo must be set to NULL by the caller, if the details of errors are not needed.

The following section describes the flags that are defined in PCSAPI32.H.

Flags for the pErrorInfo member of the PRINTINFO structure

PCS_PRINT_PRINTMODE_ERROR
PrintMode is not configured in the host session.
PCS_PRINT_PDTFILE_SIZEERR
The buffer size is not sufficient for lpPDTFile, so the file name is truncated. The nSizeNeeded member contains the actual size of the buffer required to return the PDT file.
PCS_PRINT_DSKAPPFILE_SIZEERR
The buffer size is not sufficient for lpPrtToDskAppFile, so the file name is truncated. The nSizeNeeded member contains the actual size of the buffer required to return the Print to Disk-Append file.
PCS_PRINT_DSKSEPFILE_SIZEERR
The buffer size is not sufficient for lpPrtToDskSepFile, so the file name is truncated. The nSizeNeeded member contains the actual size of the buffer required to return the Print to Disk-Separate file.
PCS_PRINT_PRINTERNAME_SIZEERR
The buffer size is not sufficient for lpPrinterName, so the printer name is truncated. The nSizeNeeded member contains the actual size of the buffer required to return the printer name.

Return Code

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.

Example

{
   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);
}

pcsSetPrinterSettings

3270 5250 VT
Yes Yes Yes

The pcsSetPrinterSettings function controls the host session printer settings (similar to the File -> Printer Setup dialog settings).

Function Type

ULONG WINAPI pcsSetPrinterSettings(char cShortSessionID, const PRINTINFO * const pPrintInfo, ULONG * const pErrorInfo)

Parameter Type and Description

char cShortSessionID
Presentation space short session ID.
const PRINTINFO * const pPrintInfo
Pointer to PRINTINFO structure, where the printer settings are mentioned.
nFlags
Combination of bit flags that indicates which members in the structure are valid. These flags can be used independently or by ORing them together to restore the property page (defined in PCSAPI32.H). The flags, along with the corresponding valid members in the structure, are as follows:
Flag
Valid members in the structure
PCS_PRINT_PDT
bPDTMode, lpPDTFile
PCS_PRINT_PRINTMODE
nPrtMode, lpPrtToDskAppFile, lpPrtToDskSepFile, lpPrinterName
PCS_PRINT_PROMPT_DIALOG
bPromptDialog
nBufSize
Must be set to 0. This is ignored.
nSizeNeeded
Must be set to 0. This is ignored.
bPromptDialog
Possible values are as follows:
  • If TRUE, the Printer Setup dialog is shown before printing.
  • If FALSE, the Printer Setup dialog is not shown before printing.
bPDTMode
Possible values are as follows:
  • If TRUE, the connection is set to PDT mode.
  • If FALSE, the connection is set to non-PDT mode (GDI mode).
lpPDTFile
Used only if bPDTMode is set to TRUE. This is ignored if bPDTMode is set to FALSE.

This is a null-terminated string containing the name of the PDT file and must be one of the following:

  • NULL

    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.

  • File name, without the path

    lpPDTFile in the PDFPDT subfolder in the Z and I Emulator for Windows installation path is used.

  • Fully qualified path name of the file

    If lpPDTFile does not exist, the API fails.

nPrtMode
This is an enumerated value that indicates the PrintMode of the connection. The enum data type PRINTMODE is defined in PCSAPI32.H. The nPrtMode setting must be one of the following:
  • PrtToDskAppend (Print to Disk-Append mode)

    This is equivalent to selecting the Append option in the host session Printer Setup -> Printer -> Print to Disk dialog.

  • PrtToDskSeparate (Print to Disk-Separate mode)

    This is equivalent to selecting the Separate option in the host session Printer Setup -> Printer -> Print to Disk dialog.

  • WinDefaultPrinter (Windows Default Printer mode)

    This is equivalent to selecting the Use Windows Default Printer option in the host session Printer Setup dialog.

  • SpecificPrinter (Specific Printer mode)

    This is equivalent to selecting a printer in the host session Printer Setup dialog, while leaving the Use Windows Default Printer option unchecked.

lpPrtToDskAppFile
This is used only if nPrtMode is set to PrtToDskAppend.

This is a null-terminated string containing the name of the Print to Disk-Append file and must be one of the following:

  • NULL

    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.

  • File name, without the path

    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.

  • Fully qualified path name of the file

    The directory must exist in the path, or the API will fail. It is not necessary that the file exist in the path.

lpPrtToDskSepFile
The possible values are as follows:
  • Fully qualified path name of the Print to Disk-Separate file for the session.
  • An empty string ("") if no Print to Disk-Separate file is configured for the session.
  • A truncated file name if the buffer size is not sufficient. The nSizeNeeded member contains the size of the buffer needed.
lpPrinterName
This is used only if nPrtMode is set to SpecificPrinter. It is ignored otherwise. This is a null-terminated string containing the printer name. If the printer does not exist, this member fails.

PrinterName must have the following format:

<Printer name> on <Port Name>

For example:

  • IBM InfoPrint 40 PS on Network Port
  • HP LaserJet 4050 Series PCL 6 on LPT1
ULONG * const pErrorInfo
This is filled with the extended error info when the API fails with the return code of PCS_FAILURE. pErrorInfo must be set to NULL by the caller, if the details of errors are not needed.

The following section describes the flags that are defined in PCSAPI32.H.

Flags for the pErrorInfo member of the PRINTINFO structure

PCS_PRINT_PDTMODE_ERROR
This can occur for one of one of the following reasons:
PCS_PRINT_PDTFILE_ERROR
The file or the path specified in lpPDTFile was not found.
PCS_PRINT_PRTTODSK_FILE_ERROR
This can occur for one of one of the following reasons:
PCS_PRINT_PRINTMODE_ERROR
nPrtMode cannot be set successfully. This can occur for one of the following reasons:

Return Code

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.

Example

{
   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);
}