Running the PCDRIVER Utility

SYSTEM/NXSERVICES/PCDRIVER is an ALGOL program that accepts a single string parameter. The parameter must either contain the program's instructions, or the name of a file containing the program's instructions.

Syntax

When the string parameter contains the name of a file, it must have the following syntax: 

FILE <file title>

The specified file must be a normal text type record oriented file. It's records will be read and the text fields of those records will be concatenated to obtain the program's instructions.

The following syntax applies to the program's instructions, whether obtained directly from the string parameter or from a file. 

──┬─<PC address>────────┬──────────────────────────────────────────────►
  └─<share designation>─┘
►─┬──────────────────────────────────────────────────────────────────┬─┤
  │     ┌◄───────────────────────── , ─────────────────────────┐     │
  └─ [ ─┴─┬─ PASSWORD ── = ──<password>──────────────────────┬─┴─ ] ─┘
          ├─ CREDENTIALS ── = ─┬─────────────────────────────┤
          │                    ├─<usercode>── / ──<password>─┤
          │                    └─ # ──<file name node>───────┤
          ├─ USERDOMAIN ── = ──<domain name>─────────────────┤
          ├─ MYIP ── = ──<IP address>────────────────────────┤
          ├─ DIR ── = ──<PC path>────────────────────────────┤
          ├─<text data option>───────────────────────────────┤
          └─ NODISPLAY ──────────────────────────────────────┘
   ┌◄──── ; ───┐
►──┴─<command>─┴────────────────────────────────────────────────────────┤

Explanation

<PC address>

An IP address (e.g. 192.63.123.123) or a DNS name (e.g. JOE.TREDY.UNISYS.COM). This program will open a TCP/IP connection to a program, LAUNCHER, which must already be running on the PC at the specified address. LAUNCHER will then perform actions on that PC corresponding to the specified commands.

Note: When LAUNCHER is run, a list of IP addresses must be specified. LAUNCHER will only accept TCP/IP connections from those IP addresses. Thus, the IP addresses of the MCP system running this program must have been specified in LAUNCHER on the target PC or this program will not succeed.

<share designation>

A Microsoft Networking share designation of the form 

\\<computer>\<share>

This program will use the MCP REDIRECTOR feature to locate and communicate with a PC, which must have Microsoft Networking server functionality enabled. If the target share name includes embedded blanks, the <share designation> component should be enclosed in quotes. The following commands are not available when the PC is specified this way: RUN, LOCKEDRUN, LOCK, and UNLOCK.

PASSWORD

Valid only when <PC address> was used.

If a password is associated with a server when it is added to the list of accepted servers where LAUNCHER Service is running, you must specify the same password when this program runs. If you do not specify the same password, LAUNCHER rejects the request.

CREDENTIALS

Valid only when <share designation> was used.

When the specified PC or PC share is configured to require credentials for access, they may be specified using this option.

The <usercode>/<password> form specifies the credentials directly.

The # <file name node> form specifies the last node of a credentials file title. The credentials file used will be NXSERVICES/CREDENTIALS/<file name node>.

Note: If CREDENTIALS is not specified and the user has a credentials file with the name NXSERVICES/CREDENTIALS/<computer> (where <computer> is taken from the specified <share designation>), that credentials file will be used.

More information on credentials files may be found in the documentation of the MCP REDIRECTOR feature.

USERDOMAIN

Valid only when <share designation> was used.

When the specified PC is configured to require a domain name for authentication, it must be supplied using this option.

MYIP <IP address>

Specifies the MCP host IP address from PCDRIVER. If the MCP host has multiple IP addresses, PCDRIVER must route communication with LAUNCHER using the IP address specified as an additional command line argument. If you do not specify a value for MYIP, the behavior of PCDRIVER is unchanged from previous releases.

DIR

Valid only when <PC address> was used.

Specifies the current working directory which LAUNCHER will use. If not specified, the TEMP environment variable on the Windows system or root directory on a Linux system will be used.

Note: When <share designation> is used, the share definition on the PC specifies the working directory.

<PC path>

Uses the PC directory syntax, such as

E:\hostfiles
Note: Using either backward or forward slashes is permitted.

<text data option>

Specifies a default for an option to the TEXTDATATOPC and the TEXTDATAFROMPC commands. See the explanation under <text data to PC command> and <text data from PC command>.

NODISPLAY

Suppresses display of error messages indicating command failure. (Syntax errors are always displayed.)

Notes:

  • This program always uses the task VALUE attribute to return an enumerated value reflecting the result of the last command performed.

  • If a command incurs an error, all subsequent commands are ignored.

  • The task VALUE attribute is loaded just before the program terminates.

Commands

The following commands can be used when running the PCDRIVER utility:

<lock command>

── LOCK ───────────────────────────────────────────────────────────────┤

LAUNCHER has a lock (mutex) which can be locked and unlocked using the LOCK and UNLOCK commands. This lock may be used to serialize actions or sequences of actions which must not overlap other (locked) sequences performed by LAUNCHER for other MCP tasks.

Note: LAUNCHER may service many MCP tasks at the same time (potentially from more than one MCP system). It runs one thread for each such MCP task, and these threads own or contend for the mutex.

<unlock command>

── UNLOCK ─────────────────────────────────────────────────────────────┤

Refer to the LOCK command.

<run command>

── RUN ────────────────────────────────────────────────────────────────►
►─┬──────────────────────────────────────┬─────────────────────────────►
  │     ┌◄─────────── , ───────────┐     │
  └─ [ ─┴─ RESULT ── = ──<integer>─┴─ ] ─┘
►─<PC program>──<arguments>────────────────────────────────────────────┤

Run the specified PC program, with the specified arguments.

The specified <arguments> include everything up to the next semicolon, except that two adjacent semicolons are treated as one semicolon included in <arguments>.

RESULT specifies the expected integer value returned by the PC program. If RESULT is specified and the value returned by the PC program does not match one of them, the PC program will be considered to have reported a failure.

Some users have found it useful to use this command to run the Microsoft supplied COMMAND and CMD programs. These programs are command interpreters which make the functionality of the Microsoft command prompt interface available. The /c parameter should be used as in the following example. Please refer to Microsoft documentation of the COMMAND and CMD programs for more information. 

RUN CMD /c rd c:\test\test1  /s /q

In this example, the CMD command interpreter will process the rd (remove directory) command. The directory to be removed is c:\test\test1. /s indicates that all subdirectories should be removed. /q indicates that rd should not request confirmation. /c indicates that CMD should terminate once it has processed the command.

<locked run command>

── LOCKEDRUN ──────────────────────────────────────────────────────────►
►─┬──────────────────────────────────────┬─────────────────────────────►
  │     ┌◄─────────── , ───────────┐     │
  └─ [ ─┴─ RESULT ── = ──<integer>─┴─ ] ─┘
►─<PC program>──<arguments>────────────────────────────────────────────┤

Identical to the sequence LOCK, RUN, UNLOCK.

<binary data to PC command>

── BINARYDATATOPC ──<title>──<PC file name>────────────────────────────┤

Copies the data of the specified MCP file to a newly created PC file. There must be no existing PC file of the specified name. Data is copied without translation, regardless of EXTMODE. CR and LF characters are not added.

The specified MCP file must have BLOCKSTRUCTURE=FIXED and might not have FRAMESIZE=4. The usercode running this program must have access rights to read the file.

The <title> is the MCP file title with the exception that any node with only a single period (.) does not require surrounding double quotation marks.

<text data to PC command> 

── TEXTDATATOPC ─────────────────────────────────────────────────────►
►─┬────────────────────────────────┬──────────────────────────────────►
  │     ┌◄──────── , ────────┐     │
  └─ [ ─┴─<text data option>─┴─ ] ─┘
►─<title>──<PC file name>────────────────────────────────────────────┤

Copies the data of the specified MCP file to a newly created PC file. There must be no existing PC file of the specified name.

If the MCP file data is in EBCDIC, it will be translated to an ASCII based character set using a translation selected as described in the explanation of the CCSVERSION <text data option>.

CR and LF characters are added after the last non-space character from each record. As a result, trailing spaces are truncated.

The specified MCP file must have BLOCKSTRUCTURE=FIXED and may not have FRAMESIZE=4. Also, it may not have MAXRECSIZE=1 and FRAMESIZE=8. The usercode running this program must have access rights to read the file.

<binary data from PC command> 

── BINARYDATAFROMPC ──<title>──<PC file name>──────────────────────────┤

Copies the data of the specified PC file to a newly created MCP file. There must be no existing MCP file of the specified name.

Data is copied without translation. A file with MAXRECSIZE=1, FRAMESIZE=8, FILESTRUCTURE=STREAM, and EXTMODE=ASCII is created.

<text data from PC command> 

── TEXTDATAFROMPC ─────────────────────────────────────────────────────►
►─┬────────────────────────────────┬───────────────────────────────────►
  │     ┌◄──────── , ────────┐     │
  └─ [ ─┴─<text data option>─┴─ ] ─┘
►─<title>──<PC file name>──────────────────────────────────────────────┤

Copies the data of the specified PC file to a newly created MCP file. There must be no existing MCP file of the specified name.

Unless the TRANSLATE <text data option> is FALSE, the data will be translated from an ASCII based character set to an EBCDIC based character set, using a translation selected as described in the documentation of the CCSVERSION <text data option>.

A record oriented MCP file will be created. See the description of the <text data option>.

<remove command> 

── REMOVE ──<PC file name>─────────────────────────────────────────────┤

Deletes the specified PC file.

Text Data Options

All <text data option> values have a default which can be overridden in the options for the entire program or in the options for an individual command.

A value in the options for an individual command overrides any value in the options for the entire program.

<CCSVERSION option> 

── CCSVERSION ─┬─<version>───┬─────────────────────────────────────────┤
               ├─ JAPAN ─────┤
               ├─ JAPAN_V24 ─┤
               ├─ TAIWAN ────┤
               ├─ CHINA ─────┤
               ├─ KOREA ─────┤
               └─ GERMAN ────┘

The EBCDIC character set and the ASCII character set used when data is translated between EBCDIC and ASCII will be inferred from CCSVERSION as follows: 

ASERIESNATIVE
     EBCDIC:EBCDIC
     ASCII:ASCII
BRAZILIAN
CANADAEBCDIC
FRANCE
GERMAN
NORWAY
SPANISH
SWEDISH1
SWISS
     EBCDIC:LATIN1EBCDIC
     ASCII:LATIN1ISO
CZECHOSLOVAKIA
HUNGARIAN
POLISH
ROMANIAN
     EBCDIC:LATIN2EBCDIC
     ASCII:CODEPAGE1250
TURKISH
     EBCDIC:LATIN5EBCDIC
     ASCII:LATIN1ISO
LATINGREEK
     EBCDIC:LATINGREEKEBCDIC
     ASCII:LATINGREEKISO
RUSSIAN
     EBCDIC:LATINCYRILLICEBC
     ASCII:CODEPAGE1251
ARABIC20
     EBCDIC:ARABIC20EBCDIC
     ASCII:CODEPAGE1256
JAPAN
     EBCDIC:JAPANEBCDIC
     ASCII:JIS8ASCII  (ShiftJIS)
JAPAN_V24
     EBCDIC:V24EBCDIC
     ASCII:JIS8ASCII  (ShiftJIS)
TAIWAN
     EBCDIC:EBCDICUTL
     ASCII:CODEPAGE950
CHINA
     EBCDIC:EBCDICGB2312
     ASCII:CODEPAGE936
KOREA
     EBCDIC:EBCDICKSC5601
     ASCII:CODEPAGE949

The default is the system-wide value established by SYSOPS CCSVERSION and (when SYSOPS CCSVERSION is ASERIESNATIVE) SYSOPS HOSTCCS.

When SYSOPS CCSVERSION is ASERIESNATIVE, the following values of HOSTCCS enable the specified support.

HOSTCCS

Local

EBCDICUTL

TAIWAN

EBCDICGB2312

CHINA

EBCDICKSC5601

KOREA

JAPANEBCDICJBIS8

JAPAN

<sequence numbers on PC option> 

── SEQUENCENUMBERSONPC ── = ─┬─ FALSE ─┬───────────────────────────────┤
                             └─ TRUE ──┘

If FALSE, the data to or from the PC will map onto the text field of the MCP file, as inferred from FILEKIND.

If TRUE, the data to and from the PC will map onto the entire record of the MCP file, including text, sequence, and markid fields.

The default is FALSE.

FILEKIND option> 

── FILEKIND ─┬─<filekind>────────┬─────────────────────────────────────┤
             └─ DATA ──<integer>─┘

Valid only for the TEXTDATAFROMPC command. Specifies the FILEKIND of the file created.

If DATA <integer> is specified, a file with <integer> character records will be created. Otherwise, a file with 90 character records will be created.

The default is SEQDATA.

<blocking option> 

── BLOCKING ── = ──<integer>───────────────────────────────────────────┤

Valid only for the TEXTDATAFROMPC command. Specifies the number of records per block in the file to be created.

The default will depend on the record size. For 90 character records, the default is 30.

<UNITS option> 

── UNITS ─┬─ CHARACTERS ─┬─────────────────────────────────────────────┤
          └─ WORDS ──────┘

Valid only for the TEXTDATAFROMPC command. Specifies the UNITS of the file to be created.

Specification of both UNITS=WORDS and BLOCKING=<integer> is an error if <integer> is not divisible by 6.

The default is CHARACTERS.

<area bytes option> 

── AREABYTES ── = ──<integer>──────────────────────────────────────────┤

Valid for the TEXTDATAFROMPC command. Also applies to BINARYDATAFROMPC when used in the program default <text data option>. Specifies the number of bytes per area in the file to be created.

The default is 81000. (450 sectors at 180 bytes per sector.)

<records option> 

── RECORDS ─┬─ CRLF ─────┬─────────────────────────────────────────────┤
            └─ IMPLICIT ─┘

Valid only for the TEXTDATAFROMPC command.

CRLF specifies that the data from the PC should be scanned for CR and LF characters, which delimit record boundaries.

IMPLICIT specifies that the data from the PC should be implicitly divided into records at fixed number of character intervals. The interval is inferred from the values of FILEKIND and SEQUENCENUMBERSONPC.

The default is CRLF.

<overflow option> 

── OVERFLOW ── = ─┬─ TRUNCATE ─┬───────────────────────────────────────┤
                  ├─ FOLD ─────┤
                  ├─ WRAP ─────┤
                  └─ ERROR ────┘

Valid only for the TEXTDATAFROMPC command. Irrelevant when RECORDS=IMPLICIT.

TRUNCATE indicates that long records should be truncated. (If truncation occurs, this program will set it's task's SW1 attribute to TRUE.)

FOLD indicates that long records should be folded, with a backslash character in the last column indicating a folded line.

WRAP indicates that long records should "wrap" at word boundaries.

ERROR indicates that long records should be treated as an error.

The default is TRUNCATE.

<translate option> 

── TRANSLATE ── = ─┬─ FALSE ─┬─────────────────────────────────────────┤
                   └─ TRUE ──┘

Valid only for the TEXTDATAFROMPC command.

If FALSE, the data from the PC will not be translated, and the EXTMODE of the new file will be ASCII.

If TRUE, the data from the PC will be translated from an ASCII based character set to an EBCDIC based character set (using a translation selected as described above in the documentation of the CCSVERSION <text data option>), and the EXTMODE of the new file will be EBCDIC.

The default is TRUE.

<trimblanks option> 

── TRIMBLANKS ── = ─┬─ FALSE ─┬────────────────────────────────────────┤
                    └─ TRUE ──┘

Valid only for the TEXTDATATOPC command.

If FALSE, the records sent to the PC do not have trailing blank characters removed.

If TRUE, the records sent to the PC have trailing blank characters removed.

The default is TRUE.

Prev  Up  Next
PCDRIVER Utility  Home  Error Messages