PCSAPI Functions

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.

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 Name
  • Function Type
  • Parameter Type and Description
  • Return Code

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

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

pcsDisconnectSession

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

pcsQueryConnectionInfo

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

ConnectionInfo

The CONNECTIONINFO structure will be filled with the information about the host connection, consisting of the following information:

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

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:

pcsQuerySessionList

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 Personal Communications 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 Personal Communications, 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:

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

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

pcsSetLinkTimeout

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

pcsStartSession

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:

• PCS_HIDE
• PCS_SHOW
• PCS_MINIMIZE
• PCS_MAXIMIZE

Return Code

pcsStopSession

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

Page Setup Functions

The PCSAPI functions listed in this section enable you to control and retrieve the Personal Communications 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.

• The host session specified in the argument cShortSessionID should not be in PDT mode.
• The host session should not be printing when the API is invoked.
• The File -> Page Setup dialog should not be in use.

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:

• 3270 display
• 3270 printer
• 5250 display
• ASCII VT

5250 printer sessions are not supported.

pcsGetPageSettings

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.

nFontSize

Size of the printer font.

Note:

This is supported only for DBCS host sessions. This is ignored for SBCS host sessions.

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

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

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

Example

{ 
   ULONG Rc = 0; 

   Rc = pcsRestorePageDefaults('A', PCS_PAGE_TEXT); 

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

pcsSetPageSettings

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.

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.

nFontSize

Size of the printer font.

Note:

This is supported only for DBCS host sessions. This is ignored for SBCS host sessions.

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

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 Personal Communications 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.

• The host session should not be printing when the API is invoked.
• The File -> Printer Setup dialog should not be in use.

pcsGetPrinterSettings

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

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

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 Personal Communications 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:

• bPDTMode is set to TRUE, lpPDTFile is set to NULL, and there is no PDT file already configured for the host session.
• nPrtMode is set to PrtToDskAppend or PrtToDskSeparate, PCS_PRINT_PDT is not set in nFlags, and the host session is not already in PDT mode.
• nPrtMode is set to PrtToDskAppend or PrtToDskSeparate and bPDTMode is set to FALSE.

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:

• The folder specified in the field lpPrtToDskAppFile or lpPrtToDskSepFile does not exist or does not have write access.
• An extension is specified in the field lpPrtToDskSepFile.

PCS_PRINT_PRINTMODE_ERROR

nPrtMode cannot be set successfully. This can occur for one of the following reasons:

• The value of nPrtMode is not one of the enumerated constants of the PRINTMODE enum data type.
• nPrtMode is set to PrtToDskAppend, lpPrtToDskAppFile is set to NULL, and there is no Print to Disk-Append file already configured in the host session.
• nPrtMode is set to PrtToDskSeparate, lpPrtToDskSepFile is set to NULL, and there is no Print to Disk-Separate file already configured in the host session.
• nPrtMode is set to SpecificPrinter and the printer given in the lpPrinterName field was not found.
• nPrtMode is set to WinDefaultPrinter and there is no default Windows printer configured in the system.
• bPDTMode is set to FALSE and PCS_PRINT_PRINTMODE is not set in nFlags, but the host session PrintMode is PrtToDskAppend or PrtToDskSeparate.

Return Code

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