PLBWIN Command Line

Most of the supplied utilities (those with an extension of .plc), PLBCMP and all programs compiled by PLBCMP require either PLBWIN, PLBNET, PLBCE, or PLBCON to execute. The PLBWIN Windows runtime use the following command line format:

plbwin -{options} [-{options} ...] [{plc} [{args}]]

Parameters:

options

One of the valid command line options listed below.

plc

The name of a previously compiled PL/B program.

args

Program arguments passed to the PL/B program using the S$CMDLIN system variable.

Note the following:

1. PLBCON is a console version of PLBWIN. It does not have a default window, but rather uses the console screen. It is otherwise identical to PLBWIN and allows use of all the GUI features of the language. PLBCON provides support for both long file names and files greater than two (2) gigabytes in length. To create PLBCON, use the MAKECON utility.

2. The following options are available:

 

Option	Meaning
?	displays command line syntax help.
a	execute runtime using 'ansi.sys'.
b	force screen controls S0 through S9 to update screen.
cgi <filename>	normally used to access CGI data that has been stored into the <filename> by a PWS server which has accepted a REST request to be processed. This option causes the <filename> file CGI data to be preloaded into memory before a PL/B program starts executing. After the PL/B program starts executing, the RUNTIME object method 'CgiString' can be used to retrieve the data using CGI keywords.
d	initiate the interactive, on-line debugging mode.
dr	invokes the 'plbdbug.plc' character debugger which makes a socket connection to the 'dbgiface.plc' GUI debugger and an interactive GUI debug session is initiated. The runtime PLBDBG_LOGON keyword must be accessible by both debuggers. See the PLBDBG_LOGON keyword in the PL/B Runtime Reference manual for more information. Except for invoking the GUI debug session this debug option behaves similarly to the 'd' debug option.
delete	remove the NT Service.
e	display user count information for all runtimes and expiration time for time stamped runtimes. For the PLBWIN and PLBNET runtimes, the '-e[x]' option data is only accessible using redirected command line output to a data file using "plbwin -e3 > xxx.txt".   Specialized Licensed User Count data in condensed form is available as follows:   '-e0' - The current authorized user license count is given.   '-e1' - The current user-client count in use.   '-e2' - The current user-client count available for use.   '-e3' - The current summary of all user license counters.
f	causes the runtime to adjust the font size for the main window ( MAINWINDOW ) depending on the horizontal resolution of the screen being used. If the horizontal screen width is larger than 800 pixels, the Windows PL/B runtime sets the main window font size to be 15.0 point. In this case, the PL/B main window becomes larger by default. If this option is not used, the main window font size defaults to a 9.0 point font size which causes the main window to be smaller.
g{nnnnnnn}	allocate memory for global data area (Default is 65535). The value is specified in bytes.
h	hide the primary window.
i {ini name}	override the default .ini file.
idefault	install NT Service using default OS settings.
ilocal	install NT Service using 'NT AUTHORITY\\LocalService'.
inetwork	install NT Service using 'NT AUTHORITY\\NetworkService'.
iuser=name;pass	install NT Service using specified username/password.
mp{nn}	set maximum dbpath buffer size.
ms{nn}	override number of subwindows that may be saved.
mv{nnnnnnn}	define the maximum virtual memory size. The default value is 20MB for a normal PL/B program and 4MB for an Application Server thread task. The value is specified in bytes.
p {print device}	override the default printer device/file.
q	causes the runtime to start program execution in a quiet mode. The PLB runtime does not output the Sunbelt runtime greeting\banner when the quiet mode option is used. Also, see the runtime PLB_QUIET keyword.
s {scrn name}	override the default screen definition file selection
t	sets the wait time in seconds to receive a complete function key.
w{nn}	set default screen attribute where nn is a hex digit.
z {path}	use the specified {path} as the current working directory.

 

3. The PLB runtimes support specialized internal debugging capabilities that can be used to record PLB program execution data. There are two data collection formats that are generated depending on the debug option '-dN' that is specified.

 

A. Special Internal Runtime Debugging

 

The first internal debugging data collection format is invoked using the '-dN' options where the N can be a 0, 1, 2, 3, or 4 value. This type of internal debugging data should ONLY need to be collected upon request by Sunbelt personnel where the resulting debug data is to be analyzed by Sunbelt personnel. In general, this form of internal debugging allows Sunbelt personnel to determine the PLB program flow and the exact PLB instructions that are being executed for some PLB program scenario being evaluated. The following descriptions apply when using the form of internal debugging:

 

Option	Meaning
d0	This option identifies that the runtime internal debugging is turned off. This is the default behavior when the '-dN' option is not specified.
d1	This option is reserved for Sunbelt use.
d2	This option invokes runtime internal debugging level 2 to create and store runtime administrative data into a single file named as follows. When this runtime debug option is invoked, the PLB runtime requires that an end-user start the program execution by responding to an appropriate debug start dialog for a Windows runtime or a key input for a Linux runtime.   'plbwin.log' - Windows runtime   'plb.log' - Linux runtime   'plbwin_NNNN.log' - Windows Plbserve runtime where NNNN is a process or thread ID of the runtime.   'plb_NNNN.log' - Linux Plbserve runtime where NNNN is a process or thread ID of the runtime.
d3	This option invokes runtime internal debugging level 3 that records both runtime administrative data as described for '-d2' along with additional PLB program execution data that is captured in a snapshot of PLB program instruction codes. Like the '-d2' option, this '-d3' debug option requires the end-user to start the PLB internal debugging session manually the same as described in the '-d2' option. When this '-d3' debug option is used, the PLB runtime captures and stores program codes into alternating log files named as follows. These log files are limited to a size of '100,000' bytes resulting in a maximum program execution window of '200,000' program instruction codes that can be analyzed by the Sunbelt personnel.   'plbwin1.log' and 'plbwin2.log' - Windows runtime program debug log files.   'plb1.log' and 'plb2.log' - Linux runtime program debug log files.   'plbwin1_NNNN.log' or 'plbwin2_NNNN.log' - Windows Plbserve runtime program logfiles where NNNN is a process or thread ID of the runtime child task.    'plb1_NNNN.log' or 'plb2_NNNN.log' - Linux Plbserve runtime runtime program log files where NNNN is a process or thread ID of the runtime child task.
d4	This option invokes runtime internal debugging the same as described for the '-d3' option except the end-user is NOT required to manually start the debugging session.

Note:

1. These runtime internal debugging options are only intended to capture information that can be analyzed by Sunbelt personnel when evaluating some end-user scenario that requires details not available otherwise.

2.  The PLB runtime keyword named 'PLB_DEBUG={type}' can be used to cause the runtimes to automatically invoke internal runtime debugging. See the description of this keyword for more details. The '-d2', '-d3', or '-d4' options override the 'PLB_DEBUG' keyword setting when both the keyword and command line option is being used.

3. Starting with changes made in release 9.5C, any log files are created by default in the directory location specified by the 'PLB_SYSTEM' keyword.

4. Also, implemented in release 9.5C, additional internal runtime keywords have been implemented to expand the debugging flexibility. These runtime keywords should only be used in special debugging scenarios.

1. PLB_DEBUGLOGFILESIZE=NNNNNNNNN - This keyword changes the default internal log file size from '100,000' to the specified size. The 'NNNNNNNNN' can be specified with a value of '65535' to '500000000'. The 'NNNNNNNNN' value applies to each program log file created as described for the '-d3' option.

2. PLB_DEBUGLOGNAME={name} - This keyword specifies a user defined log file {name} to be used in place of 'plbwin' or 'plb' as described for the '-d2' and '-d3' debug options. In this case, the {name} does not contain the path.

3. PLB_DEBUGLOGPATH={path} - This keyword specifies a user defined {path} where the log files as described for the '-d2' and '-d3' options are to be created. In this case, the {path} is used instead of the path specified by the 'PLB_SYSTEM' keyword for the location of internal debug log files.

5. The PLB internal runtime debugging may be changed at the discretion of the Sunbelt personnel to allow special internal debugging data to be collected and analyzed when resolving end-user issues.

B. Runtime Profiling

A second internal debugging data collection format is implemented to generate runtime program data such that an end-user can execute a PLB profile analyzer program when evaluating PLB performance issues. The profile internal debugging can be invoked using the '-dN' options where the N can be a 5, 6, 7, or 8 value. The PLB profiling data is stored in binary format to allow as much data as possible to be collected while minimizing the profile data file size. The following descriptions apply when using the form of profile debugging:

4. Any of the options are accepted in either upper or lower case.

5. If {plc} is not specified, PLBWIN searches the current directory then each one in the PLB_PATH environment variable list, if specified, (i.e., the search paths) for the default ANSWER and MASTER files specified by the screen definition file in use.

6. If the "d" option is specified, PLBWIN searches the PLB_SYSTEM directory for the file plbdbug.plc. If unable to locate it, error U11 occurs. Once located, it then searches the search paths for the code program ({plc}) and its symbol table. If a valid symbol file is not found, the message `Symbol table not found or invalid. Debugger disabled' is displayed.

7. If {scrn file} is specified with the "s" option, it is used instead of the screen definition name built by appending ".def" to the user's TERM entry. Note: There may be a space between the "s" option and the file specification.

8. If {print device} is specified with the "p" option, it is used in place of the default printer device/file in the screen definition file. Note: There may be a space between the "p" option and the file specification.

9. If {ini file} is specified with the "i" option, the file name is used in place of the default program information file (PLBWIN.INI). Note: There is a space between the "i" option and the file specification. The name may include driver and path specifications. If an extension is not specified, the default extension (.ini) is used.

10. The .ini file name processing occurs as follows:

• The runtime qualifies and uses an INI file when the file contains any section header. A section header is an INI file record that starts with '[' and is terminated with a ']'.

• The runtime looks for and uses an INI filename found in three possible directories. The runtime always processes the INI files in the same order giving the user the ability to override globally defined parameters. The file name searching is as follows:

1. First, the runtime looks for an INI filename in the current working directory. This allows someone doing very specific and local program execution using keyword controls that override default keyword controls specified in (b) or (c) below.

2. Second, the runtime looks for an INI filename in the current user Windows directory. If the INI filename is found, it becomes the local keyword controls for the runtime. This allows someone to define workstation INI file controls. The local INI file controls can override (c) below.

3. Third, the runtime looks for an INI filename in the directory where PLBWIN.EXE is found. If the INI filename is found, it becomes the global (default) keyword controls for the runtime.

• If the runtime is started without using the '-i' option, the runtime looks for the default INI file named 'PLBWIN.INI' in the three possible areas. Any PLBWIN.INI files found in the three directories are then used to locate requested INI file keywords in the order as described in (B) above.

• If the runtime is started with the '-i' option being specified and the INI file name does not have a path specified, the runtime looks for the INI file name in the three possible directories defined in (B) above. The runtime only processes the user named INI file from the three directories defined in (b.) above. This means the 'PLBWIN.INI' is not used in this case.

• If the runtime is started with the '-i' option being specified and the INI file name does have a path specified, the runtime looks for and uses the single specified INI file if found. This case disables the runtime from processing multiple INI files as described in (B) above.

11. When a PLBWIN.EXE is being loaded from a CD-ROM, the following rules apply:

• The ANSI.DEF, DBSERIAL, and PLBWIN.INI files must exist in the same directory on the CDROM where the PLBWIN.EXE exists.

• The PLB_SYSTEM entry in the PLBWIN.INI file is ignored and its value is set to the directory on the CD-ROM where the PLBWIN.EXE exists.

12. If there is a need to install more than one NT Service for a PLB runtime, the user can copy the PLBNET or PLBWIN runtime executable to an EXE with a different name and it a runtime with a different name.

13. The runtimes allow a user command line format where an INI file can be specified and used only when the runtime is being installed as a NT Service.

14. PLBWIN, PLBCON, and PLBCLIENT have been modified to allow the Windows OS theming to be turned off. The Windows OS theming can be turned off by naming the executable file name as '<name>5.exe'. This change is being implemented to allow PL/B runtimes to executed while showing older style Windows control appearance. (10.5A).

Example:

 

Copy 'plbwin.exe' to 'plbwin5.exe'

 

Copy 'plbcon.exe' to 'plbcon5.exe'

 

Copy 'plbclient.exe' to 'plbclient5.exe'

 

Copy 'plbclicon.exe' to 'plbclicon5.exe'

 

Copy 'plbwin.exe' to 'username5.exe'

Command Line Examples:

plbwin

Use the default screen definition file built by appending '.def' to the TERM environment variable entry and all the default PL/B environment characteristics therein (including the default printer device/file). Attempt to initiate the ANSWER to MASTER program concept by searching the search paths for the ANSWER and MASTER programs specified in the screen definition file in use.

 

plbcon test

Use the default screen definition file and then append the PL/B Code extension specified in the screen definition file to 'test' and attempt to load it from one of the search paths.

 

plbwin -d answer.plc

Use the default screen definition file and attempt to load 'plbdbug.plc' from the PLB_SYSTEM directory. Once successful, attempt to load the program 'answer.plc' and corresponding symbol table file 'answer.sym' from within the search paths. Note: there is a space between the "d" and the file name.

 

plbwin -s scrndef.def MASTER.PLC

Override the default screen definition file and use 'scrndef.def' in its place, search the search paths for 'MASTER.PLC'. Note: there is a space between the "s" and the file name.

 

plbwin -p \usr\spool\report1.lst report.plc

Override the specified printer device/file name within the default screen definition file with '\usr\spool\report1.lst' in its place, search the search paths for 'report.plc'. Note: there is a space between the "p" and the file name.

 

plbwin test.plc option1

Use the default screen definition file and attempt to load 'test.plc' from one of the search paths. The argument to 'test.plc' is '*.pls'. The string "option1" is placed in the system variable S$CMDLIN.

 

plbwin -d -g25600 test.plc

Each option must be specified separately.

 

 

See Also: PLBWIN Runtime Requirements, PLBWIN INI File Format, PLBWIN Keywords, Compiler and Runtime Options