Production Management System
Transporter
Programmer/Operator Reference
Manual
Center for Information Services
Supporting Washington State’s Community and Technical Colleges
Center for Information Services
3101 Northup Way, Suite 100
Bellevue, WA 98004-1449
Phone 425.803.9700
http://www.cis.ctc.edu
Printing History
1987
April 2003
Table of Contents
Section I: Introduction and Setup .................................................. 1
Introduction .............................................................................................................................1
Transporter Setup...................................................................................................................2
Restore Files and Programs .............................................................................................2
Initialize the Queue and History Files ...............................................................................3
Initialize or Build the Node File .........................................................................................3
Transporter UDC Files ......................................................................................................5
Test the Installation...........................................................................................................5
Section II: Operation and Use ........................................................ 7
Using the Command Interface...............................................................................................7
Transporter Command Syntax ..............................................................................................8
Transporter Commands .........................................................................................................8
Commands to Initiate Data Transfer.................................................................................8
Commands to Monitor and Maintain Transfer Requests ..................................................8
Commands to Maintain the Transporter System ..............................................................9
Miscellaneous Commands................................................................................................9
MPE Commands...............................................................................................................9
Command Descriptions.....................................................................................................9
ALTER Command......................................................................................................10
DELETE Command ...................................................................................................11
DO Command ............................................................................................................12
GET Command..........................................................................................................13
INIT Command ..........................................................................................................15
MSG Command .........................................................................................................16
PRINT Command ......................................................................................................17
REORG Command ....................................................................................................18
RESET Command .....................................................................................................19
SEND Command .......................................................................................................20
SHOW Command (Operator) ....................................................................................22
SHOW Command (User) ...........................................................................................23
SHUTDOWN Command ............................................................................................26
STARTUP Command ................................................................................................27
EXIT and HELP Commands ......................................................................................28
Section III: Maintenance................................................................ 29
Queue File Maintenance.......................................................................................................29
History File Maintenance .....................................................................................................29
Using the REORG Command...............................................................................................30
Node File Maintenance.........................................................................................................30
Section IV: Transporter System Internals ................................... 31
Transporter Data Files..........................................................................................................31
TPQUE............................................................................................................................31
TPQUEK .........................................................................................................................31
TPHIST ...........................................................................................................................31
TPNODE .........................................................................................................................32
TPFCY ............................................................................................................................32
TPHELP ..........................................................................................................................32
Transporter Programs..........................................................................................................35
TPCMD (TP1003C).........................................................................................................35
TPMON (TP1001C) ........................................................................................................35
TPSLV (TP1002C) ..........................................................................................................35
Appendix A: Programmatic Access to Transporter ................... 37
Appendix B: Transporter Error Codes ........................................ 39
Section I: Introduction and Setup
Section I provides a brief introduction to Transporter and describes the steps you need to
complete in order to set up Transporter.
Introduction
Transporter is a file transfer utility that uses DS lines (distributed system lines) in a DS
network (DSN) to move files from one HP3000 to another. The system accepts transfer
requests through a command interface program and then executes these requests in
priority and chronological sequence in an offline fashion.
Requests entered into the system are placed in one of five request queues. These queues
in order of priority are: System, Supervisor, High (or Urgent), Normal, and Low. All
queues except System and Supervisor are available to the “normal” user.
All requests entered into the system are assigned a one- to four- digit Job Identification
Number. This number is used in the maintenance commands to refer to a specific request.
Once requests have been completed the queue file record is deleted and added to a history
file.
Center for Information Services
-1-
April 2003
Transporter Setup
To set up Transporter, you need to complete the following tasks:
•
Restore files and programs
•
Initialize the queue and history files
•
Initialize or build the node file
•
Transporter UDC files
•
Test the installation
Restore Files and Programs
To set up the Transporter for use on an HP3000, first the program and data files must be
installed. These include:
1
TPCMO.EXC.TSS
2
TPMON.EXC.TSS
3
TPSLV.EXC.TSS
4
TPQUE DATA. TSS
5
TPQUEK.DATA.TSS
6
TPNODE.DATA. TSS
7
TPFCY.DATA.TSS
8
TPHELP.OATA.TSS
9
TPHIST.DATA.TSS
These may be Restored from a Store tape created on any system with the Transporter
already installed.
Center for Information Services
-2-
April 2003
Initialize the Queue and History Files
To initialize the Queue and History files, run the command interface program:
:RUN TPCMD.EXC.TSS
At the prompt supplied, enter the initialize commands:
TPCMD> INIT Q
TPCMD>INIT HIST
Then exit :
TPCMD>EXIT
Initialize or Build the Node File
If a node file already exists (LISTF TPNODE.DATA.TSS), first unscramble the data in
the file by running the command interface and use the INIT NODE command as follows:
:RUN TPCMD.EXC.TSS;INFO="INIT NODE;U"
Then open (TEXTIN) the file into the editor to make changes. If the node file does not
already exist, go directly to the editor to build one.
The node file must contain one record for each valid destination node and one record for
the local system. Records are free-format with four (4) fields separated by commas. If
any of the four fields are unused or empty, the comma for that field must still be present
as a placeholder. The four data items in order are:
1. DSLINE name of the target node, this is referred to by Transporter as the
nodename
2. Node Type
3. Node Group Number of one to three digits
4. Logon ID of the Transporter supervisor ID on the target system. Records are in
this format
nodename,nodetype,nodegroup, supervisor-logon
nodename
This entry is 1 to 8 characters long and must match the
appropriate DSLINE name used to reach this node. A good
source of valid nodenames to be entered into the TPNODE file
is the NETCON database for DSN/DS.
node type
This entry is 0 to 8 characters long. If nonblank, valid entries
are:
HOME indicates that this node is the local system.
TAPE indicates that file transfer to this node is available by
tape exchange only
Center for Information Services
-3-
April 2003
nodegroup
This entry is 1 to 3 numeric digits long. It is an arbitrary
number assigned to separate the nodes into groups. It is used
by the Transporter to allow multiple copies of Transporter to
run while each processes only requests for a specific group.
Supervisor-login
This entry is 1 to 35 characters long and is the logon ID
including passwords for the Transporter supervisor on the
target system. Usually this ID is MGR.TSS but
MANAGER.SYS and OPERATOR.SYS are also acceptable.
Use only the username and account do not include a jobname
or groupname.
Enter all data into the TPNODE file in upper case only.
Examples:
PROl,HOME,00l,MGR/PROlMGR.TSS
DEV,00l,MGR/SECRET.TSS
OA,00l,MGR/DONTlOOK.TSS
ROIO,002,MGR/PASSOIO.TSS
RO30,002,MGR/PASSO30.TSS
R122,TAPE,TOOO,MGR.TSS
After modifying or adding data to the node file keep the file as an Unnumbered editor
file.
/KEEP TPNODE.DATA.TSS,UNN
Then scramble the data in the file to preserve security. To do this run the command
interface and use the INIT NODE command as follows:
:RUN TPCMD.EXC.TSS;INFO="INIT NODE;S"
Center for Information Services
-4-
April 2003
Transporter UDC Files
The following UDC’s should be included in the account UDC file for the SYS account:
TPSTART GRP=l
OPTION NOLlST
RUN TPCMD.EXC.TSS;INFO:"STARTUP !GRP"
***
TPSHUT GRP=!
OPTION NOLIST
RUN TPCMD.EXC.TSS;INFO="SHUTDOWN !GRP"
***
Additionally, the following UDC should be included in the system UDC file:
TPCMD INFO=" "
RUN TPCMD.EXC.TSS;INFO="!INFO"
***
Test the Installation
To test the installation of Transporter, logon to the operator console as OPERATOR.SYS
and start the Transporter using the UDC's:
:TPSTART
After a few minutes the message "Transporter System Initiated" should be displayed on
the system console.
Then shut the Transporter down:
:TPSHUT
After a few minutes the message "Transporter System Shutdown" should be displayed on
the system console.
Center for Information Services
-5-
April 2003
This page inserted for back-to-back printing.
Center for Information Services
-6-
April 2003
Section II: Operation and Use
This section describes how to use the Transporter commands and lists each command and
the parameters associated with it.
Using the Command Interface
Interaction with the Transporter system for both operators and users is through the
command interface program TPCMD. This program will function at all times whether the
transfer facility is operational or not. Transfer requests made while the transfer facility is
non-operational will not be acted upon until the transfer facility has been started by the
system operator.
There are two methods of running the command interface program: multiple command
mode or single command mode. To enter multiple command mode enter:
:RUN TPCMD.EXC.TSS
or if the UDCs are installed:
:TPCMD
In this mode, the user will be prompted for input and prompting will continue until an
EXIT command is entered. In batch, input lines should be included in the $STDIN file
(the job stream file) immediately following the RUN TPCMD... with the last input record
being an EXIT.
To enter single command mode enter:
:RUN TPCMD.EXC.TSS;INFO="any valid Transporter command"
or if the UDCs are installed:
:TPCMD "any valid Transporter command"
In this mode the command string entered will be acted upon, then the command interface
program will terminate. This method may also be used in batch processing.
Center for Information Services
-7-
April 2003
Transporter Command Syntax
Transporter command syntax is similar to MPE command syntax. With a command verb
entered after the prompt, followed by a parameter string. Major parameters are separated
from each other by a semi-colon (;) except for the DSLINE name or nodename, it is
delimited by a colon (:).
Users from the SYS account and from the TSS account are recognized as Supervisory
Users and may enter any Transporter command. All other users may enter a subset of the
commands available. Also, some commands have additional options available for
Supervisory Users.
Commands available to all users are: ALTER, DELETE, MSG, PRINT, RESET, SEND,
SHOW, HELP, and EXIT.
Additional commands for Supervisory Users are: INIT, GET, REORG, SHUTDOWN,
STARTUP, and SHOW ALL.
Transporter Commands
Transporter commands fall into four functional groups. Those groups and the commands
in them are:
•
Commands to initiate data transfer: GET, MSG, PRINT, and SEND.
•
Commands to monitor and maintain transfer requests: ALTER, DELETE.
RESET, and SHOW.
•
Commands to maintain the Transporter system: INIT, REORG, SHUTDOWN,
and STARTUP.
•
Miscellaneous commands: DO, HELP and EXIT.
Commands to Initiate Data Transfer
GET
Use to retrieve a file from a remote system. This command is available
only to the system operator or manager and can be used only to copy files
to the SYS account.
MSG
Use to send a message to the operator console on a remote system. The
message is also logged to the history file of the remote system.
PRINT
Use to send a file to the line printer on a remote system, with or without
using carriage control. Environment files are also supported.
SEND
Use to send a file from the local system to a remote system. This is the
most commonly used command in this category.
Commands to Monitor and Maintain Transfer Requests
ALTER
Use to change the priority or the destination traits of a request.
DELETE
Use to remove a request from the Transporter queue. Jobs already in
Center for Information Services
-8-
April 2003
progress cannot be deleted. Jobs cannot be deleted from the history file.
RESET
Use to remove the error flag from a request that was aborted and return it
to a waiting state.
SHOW
Use to display the queue file, the history file, an individual job from the
queue file, or the list of valid nodenames. Individual job numbers cannot
be displayed from the history file.
Commands to Maintain the Transporter System
INIT
Use to purge all data from the queue file or the history file and reset
these files to their initial conditions. Also use to scramble or
unscramble the passwords in the node file.
REORG
Use to maintain the queue file and the history file without destroying
the data contained in them.
SHUTDOWN Use to disable the transfer operation. This command is issued once for
each Transporter task running. The SHUTDOWN request will not be
processed until any in-progress request has completed.
STARTUP
Use to enable the transfer operation. This command initiates a batch job
with the job name of: TPnnnn, where nnnn is the number of the
nodegroup.
Miscellaneous Commands
DO
Use to redirect command input to a disc file.
HELP
Use to display command syntax. All commands are displayed.
Commandscannot be displayed individually..
EXIT
Use to terminate the command interface program.
MPE Commands
MPE commands may be entered at the TPCMD> prompt by preceding the command with
explanation mark (!). Any command allowed by the COMMAND intrinsic may be used.
UDCsare not allowed.
Command Descriptions
On the following pages are the descriptions of the Transporter commands. These
descriptions are organized in alphabetical order showing first the individual command
syntax followed by explanations of the use of the command and its parameters.
Items specified in square brackets ([ ]) are optional. If multiple items are enclosed in the
same pair of brackets, only one may be specified if used. Items not enclosed are
mandatory parameters.
Center for Information Services
-9-
April 2003
ALTER Command
ALTER is used to change the priority or the destination traits of a request.
ALTER jobid#
[;HIGH]
[;NORM[AL]]
[;LOW]
[;TAPE]
[;SUP]
[;SYS]
[; USER=username .acctname]
[; NODE =nodename]
[;INODE= [intermediate-nodename]]
[nodetype]]
ALTER Command Parameters
jobid#
The one- to four-digit Job Number assigned to the request at the time it
was first entered.
;HIGH
;NORMAL
;LOW
;TAPE
;SUP
;SYS
These are the job priorities. If the job priority is to be changed, select
one of these to append to the ALTER command.
;USER=
Use this parameter to alter the logon user that Transporter will use to
logon to the remote system for this request. If specified, both the
username and account name must be specified.
;NODE=
Use this parameter to alter the nodename of the remote system with
which the transfer will take place.
;INODE=
Use this parameter to alter the NODE TYPE or intermediate nodename
(these two data items share the same field in the queue file records).
Note: SUP (Supervisor) and SYS (System) are only available to
Supervisory users.
Center for Information Services
-10-
April 2003
DELETE Command
DELETE is used to remove a request from the Transporter queue. Jobs already in
progress cannot be deleted. Jobs cannot be deleted from the history file.
DELETE jobid#[,jobid#...]
DELETE Command Parameters
jobid#
This parameter indicates the Job Number of the request to be deleted
from the Transporter queue. Supervisory Users may delete any
request; all others can delete requests only for the MPE account they
are currently logged on under.
Requests will be deleted from the queue file only. Deleted requests
are not recorded in the history file.
Center for Information Services
-11-
April 2003
DO Command
The DO command directs the Transporter to execute commands stored as an MPE disc
file.
DO filename
;EXIT
;NOEXIT
DO Command Parameters
filename
The name of an MPE disc file containing valid Transporter commands.
The file must be a sequential, unnumbered file of fixed length ASCII
records. Record length may be up to 252 characters.
;EXIT
;NOEXIT
Use this parameter to select the action of the Transporter after the end
of file has been reached on the DO file. If EXIT is specified, the
Transporter command interface will terminate at end of file. With
NOEXIT, the user will be prompted for more command input. This
parameter is ignored if the command interface is in the single
command mode (by using the ;INFO= option). Default is EXIT.
Center for Information Services
-12-
April 2003
GET Command
GET is used to retrieve a file from a remote system. This command is available only to
the system operator or manager and can be used only to copy files to the SYS account.
GET
filename[,newfilename]:node name
[;HIGH]
[;NORM[AL]]
[;LOW]
[;TAPE]
[;SUP]
[;SYS]
[;RET[RY]]
[;NORET[RY]]
[;USER=
[username]]
[username .acctname]]
GET Command Parameters
filename
The name of the file to be retrieved from the remote system. If no group
or account is specified in the name and the USER parameter is not
specified, the group and account of the user making the request is
assumed. If USER is specified, the account of the USER is assumed for
a non-specified account and PUB is assumed for a non-specified group.
Lockwords may also be specified; default of no lockword is assumed.
,newfilename
Use this parameter to give a different name to the file resulting from the
request than the name to which it would have defaulted. If not specified,
the default for the GET command is “filename” minus the group and
account. (This will cause the file to be retrieved to the group and
account that Transporter is running in, usually SYSMGR.SYS.)
:nodename
This is the DSLINE name of the remote system to be used in the
request. Nodenames not present in the Node File will not be accepted.
;HIGH
;NORMAL
;LOW
;TAPE
;SUP
;SYS
These are the job priorities. If needed, select one to be appended to the
end of the GET command. If not specified, NORMAL is assumed. SUP
(Supervisor) and SYS (System) are only available to Supervisory Users.
;RETRY
;NORETRY
This parameter specifies that upon failure of the Transporter to satisfy a
request, the request be retried after a minimum of five minutes has
elapsed. (Note: If there is another request to be processed, more than
five minutes may elapse before the retry is attempted.) Default is
NORETRY. However, if a DSLINE error is detected as the reason for
the failure, a RETRY is attempted regardless of which is specified.
Center for Information Services
-13-
April 2003
;USER=
Use this parameter to specify the logon ID to be used by Transporter to
logon to the remote system for this request. If the account is not
specified, the account of the user making the request is assumed. If
USER is not specified at all and the account in “filename” is different
than the requesting user's account, then MGR is used with the account
from “filename”. If USER= is not specified and the account of
“filename” matches the logon account of the requesting user, then the
same logon ID as the requesting user is assumed.
Center for Information Services
-14-
April 2003
INIT Command
INIT is used to purge all data from the queue file or the history file and reset these files to
their initial conditions, or to scramble or unscramble the passwords in the node file.
INIT
[Q]
[HIST]
[NODE [;S][;U]]
INIT Command Parameters
Q
HIST
NODE
;S
;U
Select one:
•
Q specifies the queue file (TPQUE).
•
HIST specifies the history file (TPHIST).
•
NODE specifies the node file (TPNODE).
To be used only with NODE.
•
;S specifies the password data in the node file is to be scrambled.
•
;U specifies the passwords should be unscrambled.
Note: Transporter will recognize whether or not the passwords are
scrambled and use them accordingly.
Center for Information Services
-15-
April 2003
MSG Command
MSG is used to send a message to the operator console on a remote system. The message
is also logged into the history file of the remote system.
MSG
nodename:message-text
(Message-text is a maximum of 80 characters)
MSG Command Parameters
nodename:
This is the DSLINE name of the remote system to be used in the
request. Nodenames not present in the Node File will not be accepted.
The message-text will be sent to this system's console as a TELLOP
message.
message-text
This is the text of the message to be sent to the remote-system. All
characters following nodename: will be sent. No special consideration is
needed for quotation marks, apostrophes, etc.
Note: Characters highlighted in reverse video are added to the start of message text.
Sending system information is also added to the message.
Messages are logged to the history file of both the sending and receiving systems.
Center for Information Services
-16-
April 2003
PRINT Command
PRINT is used to send a file to the line printer on a remote system, with or without
carriage control. Environment files are also supported.
PRINT filename:nodename
[;HIGH]
[;NORM[AL]]
[; LOW]
[;TAPE]
[;SUP]
[;SYS]
[;CCTL]
[;ENV=filename]
[;USER=
[username]]
[username.acctname]]
PRINT Command Parameters
filename
This parameter is the name of the file to be copied (FCOPY) to the
device LP on the remote system. If the group and/or account is not
specified, these are assumed to be the same as the logon group and/or
account of the requesting user.
:nodename
This is the DSLINE name of the remote system to be used in the
request. Nodenames not present in the Node File will not be accepted.
;HIGH
;NORMAL
;LOW
;TAPE
;SUP
;SYS
These are the job priorities. If needed, select one to be appended to the
end of the PRINT command. If not specified, NORMAL is assumed.
SUP (Supervisor) and SYS (System) are only available to Supervisory
Users.
;CCTL
If used, this parameter specifies that the first character in the file being
sent should be interpreted as a carriage control character.
;ENV=
If used, this parameter specifies the name of an environment file to be
used in printing the file. The environment file must reside on the
remote system where the printing is to be done.
;USER=
This parameter can be used to specify the logon ID to be used by
Transporter to logon to the remote system for this request. If the
account is not specified, the account of the user making the request is
assumed. If USER= is not specified at all and the account in “filename”
is different than the requesting user's account, then MGR is used with
the account from “filename”. If USER= is not specified and the account
of “filename” matches the logon account of the requesting user, then
the same logon ID as the requesting user is assumed.
Center for Information Services
-17-
April 2003
REORG Command
REORG is used to reset the EOF pointer for the TPQUE file to agree with the actual
EOF. This command also cycles the TPHIST file.
REORG
REORG has no parameters
REORG Command Parameters
The REORG command accepts no parameters. The REORG command should only be
used while the Transporter transport mechanism is shut down. Also, no users or jobs that
might issue Transporter command should be logged on the system while the TPREORG
job is running.
Center for Information Services
-18-
April 2003
RESET Command
RESET is used to remove the error flag from a request that was aborted and return it to a
waiting state.
RESET jobid#
RESET Command Parameters
jobid#
This parameter is the Job Number of the request to be returned to the Waiting
state. Any job, regardless of status, may be reset; therefore, care should be
used in RESETing jobs that are marked In Progress (IP).
When a job is RESET, the queue file record for the request is marked as
Waiting (WT) and zero (0) is moved to the Error Code. The Original Error
Code field and Retry Count field are not modified.
Center for Information Services
-19-
April 2003
SEND Command
SEND is used to send a file from the local system to a remote system.
SEND
filename[,newfilename]: nodename
[;HIGH]
[;NORM[AL]]
[;LOW]
[;TAPE]
[;SUP]
[;SYS]
[;REP[LACE]]
[;NOREP[LACE]]
[;RET[RY]]
[;NORET[RY]]
[;DEL[ETE]]
[;NODEL[ETE]]
[;RELE[ASE]]
[;NOREL[EASE]]
[;USER=
[username]]
[username.acctname]]
SEND Command Parameters
filename
This parameter is the name of the file to be sent to the remote system. If
the group and/or account is not specified, these are assumed to be the
same as the logon group and/or account of the requesting user.
newfilename
Use this parameter to give a different name to the file resulting from the
request than the name to which it would have defaulted. If not specified
and USER= is not specified, the default is the same name as in
“filename”. If not specified and USER= is specified, the default is
“filename” minus the group and account specification (this will have the
effect of putting the file in the home group of the specified username).
:nodename
This is the DSLINE name of the remote system to be used in the
request. Nodenames not present in the Node File will not be accepted.
;HIGH
;NORMAL
;LOW
;TAPE
;SUP
;SYS
These are the job priorities. If needed, select one to be appended to the
end of the SEND command. If not specified, NORMAL is assumed.
SUP (Supervisor) and SYS (System) are only available to Supervisory
Users.
;USER=
Use this parameter to specify the logon ID to be used by Transporter to
logon to the remote system for this request. If the account is not
specified, the account of the user making the request is assumed. If
Center for Information Services
-20-
April 2003
USER= is not specified at all and the account in “filename” is different
than the requesting user’s account, then MGR is used with the account
from “filename”. If USER= is not specified and the account of
“filename” matches the logon account of the requesting user, then the
same logon ID as the requesting user is assumed.
;REPLACE
If REPLACE is specified, any file on the remote system with the same
;NOREPLACE name as the file to be copied is purged before the transfer is attempted.
The default is NOREPlACE.
;RETRY
;NORETRY
This parameter specifies that upon failure of the Transporter to satisfy a
request, that the request be retried after a minimum of five minutes has
elapsed. (Note: If there is another request to be processed, more than
five minutes may elapse before the retry is attempted.) Default is
NORETRY. However, if a DSLINE error is detected as the reason for
the failure, a RETRY is attempted regardless of which is specified.
;DELETE
;NODELETE
If DELETE is specified, this parameter indicates that upon successful
completion of the request, the original file is to be purged from the
sending system. Default is NODELETE.
;RELEASE
;NORELEASE
If RELEASE is specified, this parameter indicates that upon successful
completion of the request the new file created on the receiving system is
to have an MPE RELEASE command issued to allow any user to access
the file. Default is NORELEASE.
SEND Command Example
:TPCMD
TPCMD 5.0 *
11/06/02
Center for Information Services
3101 Northup Way, Bellevue, WA
98004
TPCMD> SEND TPSLATE:DEV;USER=DCWS.SSDEV
FILE SIZE = 626 SECTORS
ESTIMATED TRANSMIT TIME
0 HRS 06 MIN @ 4800 BPS
0 HRS 04 MIN @ 9600 BPS
JOB ACCEPTED JOBID=0002
TPCMD> EXIT
END OF PROGRAM
TRANSPORTER JCW Values
If any job is accepted by the Transporter and is assigned a Job ID Number, the JCW
“TPJCW” will be set to equal the assigned number. This number will be in the range of
0-9999. If an error occurs, the TPJCW will be set to a value of 10000 + the error code.
Center for Information Services
-21-
April 2003
SHOW Command (Operator)
SHOW is used to display the queue file, the history file, an individual job from the queue
file, or the list of valid nodenames. Individual job numbers cannot be displayed from the
history file.
S[HOW]
[jobid#]
[ALL]
[NODE]
[Acctname]
[@
[username.acctname]
[@.@]
[!]
[;HIST]
[;BOTH]
[;status-code]
Default SHOW is for the user's logon username and account.
From SYS account users, SHOW @, SHOW @.@ and SHOW ALL will have identical
results.
Center for Information Services
-22-
April 2003
SHOW Command (User)
SHOW is used to display the queue file, the history file, an individual job from the queue
file, or the list of valid nodenames. Individual job numbers cannot be displayed from the
history file.
S[HOW]
[jobid#]
[NODE]
[acctname]
[username.acctname]
[;HIST]
[;BOTH]
[;status-code]
Default SHOW is for the user's logon username and account.
From a non-SYS account, SHOW acctname and SHOW username.acctname can only
show the user's logon account.
SHOW Command Parameters
Note: Refer to syntax descriptions for information on which parameters may be
specified by Supervisory Users only; see SHOW Command (Operator).
jobid#
Indicates the Job Number of a queue file record for which the
detail information is to be displayed.
ALL
Indicates that a summary display of all records in the specified
file(s) is to be displayed.
NODE
Indicates that a list of valid nodes is to be displayed from the
Node File (TPNODE).
acctname @
Indicates that a summary display of all records for the specified
account in the specified file(s) is to be displayed.
username.acctname
@.@
Indicates that a summary display of all records for the specified
username and account in the specified file(s) is to be displayed.
! (exclamation
point)
Indicates that detail information for all records (including control
records) in the specified file is to be displayed. This is the only
way to get a detail display from the History File (TPHIST).
Select one of the above listed parameters. Default is to show a summary display of
records in the Queue File (TPQUE) for the logon username and account.
Center for Information Services
-23-
April 2003
;HIST
;BOTH
Use these parameters to specify the file from which the display is to
be done.
If not specified, display is from the Queue File (TPQUE).
If ;HIST is specified, display is from the History File (TPHIST)
If ;BOTH is specified, display is from both files.
;status-code
If used, may be one of: WT, IP, CD, CX, ER, or LN. This will
cause only those records of the specified status to be displayed.
SHOW Summary Display Headings
The SHOW summary display prints a heading line across the screen with one line below
the headings for each record to be displayed. Headings and values are:
Q
Values:
(Queue Priority)
* (asterisk)
S
H
N
L
T
System
Supervisor
High or Urgent
Normal
Low
Tape
JOB#
This is the Job Number.
NODENAME
This is the DS LINE name of the remote system.
USERNAME
This is the Username of the requesting user.
ACCOUNT
This is the Account name of the requesting user.
RT
Values:
(Request Type)
STA
SF
GF
PR
PC
MS
** (two asterisks)
SEND
GET
PRINT
PRINT ;CCTL
MSG
SHUTDOWN
Values:
(Request Status)
Center for Information Services
WT
IP
CD
CX
ER
LN
Waiting
In Progress
Completed
Completed from remote system
Error
Error (DSLINE error)
-24-
April 2003
ERR#
(Current Error Code)
REP
(Replace/NoReplace)
DEL
(Delete/NoDelete)
RET
(Retry/NoRetry)
REL
(Release/NoRelease)
FILENAME/MSG
This code may be either a DSN/DS error (these may be
found in Appendix B of the DSN/DS manual) or an MPE
File System or Command Interpreter error. User discretion is
needed to determine which error source applies.
Values:
N
NOREPLACE
Y
REPLACE
Values:
N
NODELETE
Y
DELETE
Values:
N
NORETR
Y
RETRY
Values:
N
NORELEASE
Y
RELEASE
The first 16 characters of the filename or message to be
transferred.
Center for Information Services
-25-
April 2003
SHUTDOWN Command
SHUTDOWN is used to disable the transfer operation. This command is issued once for
each Transporter task running. The SHUTDOWN request will not be processed until any
In Progress request has completed.
SHUTDOWN node-group#
SHUTDOWN Command Parameters
node-group#
This indicates the node group of Transporter batch task to be
shutdown. Transporter batch tasks have the job name TPnnnn, where
nnnn is the node-group#. If there are multiple Transporter tasks
running on the system for the same node-group, the first task to go idle
will be shut down. Therefore, a SHUTDOWN must be issued for each
Transporter task running.
Center for Information Services
-26-
April 2003
STARTUP Command
STARTUP is used to enable the transfer operation.
STARTUP node-group#[;TEST]
STARTUP Command Parameters
node-group#
This indicates the node group of the Transporter batch task to be
started. Transporter batch tasks have the job name TPnnnn, where
nnnn is the node-group. At least one STARTUP command must be
issued for each node-group to be processed. Multiple tasks for the
same node-group are also legal.
;TEST
Addition of this parameter will put the transfer facility (TPMON) into
“test” mode. Various messages about events and data being processed
will be displayed in the $STDLIST. Use of this parameter may cause a
small degradation of Transporter performance.
Center for Information Services
-27-
April 2003
EXIT and HELP Commands
EXIT is used to terminate the command interface.
E[XIT]
HELP is used to display command syntax. All commands are displayed. Commands are
notdisplayed individually.
HELP
EXIT and HELP Command Parameters
The EXIT and HELP commands do not accept any parameters. Parameters entered will
be treated as comments.
Center for Information Services
-28-
April 2003
Section III: Maintenance
Three of the Transporter data files require periodic maintenance: the Queue File
(TPQUE), the History File (TPHIST), and the Node File (TPNODE).
Queue File Maintenance
The Transporter Queue File is an MPE KSAM file. As records are added to and deleted
from the queue, the EOF pointer will only increase and not decrease. Therefore,
periodically, before the EOF pointer approaches the FILE LIMIT of the file, the file must
be either reorganized or reinitialized. The most desirable method is the reinitialization,
which is done by using the INIT Q command. This command will, however, destroy all
data in the queue file. Therefore, if there are outstanding requests in the queue, a
reorganization must be used. To do this, use the REORG command (described below).
When Queue File is more than 70% full, the Transporter monitor program (TPMON) will
display the following message to the operator console during its startup initialization:
WARNING THE TRANSPORTER QUEUE FILE NEEDS MAINTENANCE
History File Maintenance
The Transporter History file is an MPE sequential file. Records are added to the end of
the file during Transporter operation, No operation removes records from the History
File. As records are added, the EOF pointer for the file will approach the FILE LIMIT,
and like the Queue File, the History File must be cleaned before the two limits are equal.
To do this, use the REORG command (described below). If this file is more than 70%
full, the Transporter monitor program (TPMON) will display the following message to
the operator console during its startup initialization:
WARNING THE TRANSPORTER HISTORY FILE NEEDS MAINTENANCE
If you issue a REORG to maintain the Queue File, the REORG will also apply to the
History File. For the History File this means the current file is shifted into a five-file
cycle of previous files (TPHISTI through TPHIST5) and a new working History File is
built (TPHIST).
An alternate method of maintaining the History File is by using the INIT HIST
command. This command will, however, purge all data from the History File and,
therefore, should only be used if there is no longer any reason to refer to the data
contained in the file.
Both the REORG and INIT must be done with the Transporter shut down.
Center for Information Services
-29-
April 2003
Using the REORG Command
To maintain the Queue File or History File when they are 70% or more full, use the
following steps:
1. Shut down the Transporter using either the OPI command OPI TSTOP
or type :TPSHUT
Wait for the message “Transporter System Shutdown.”
2. To reorganize the Transporter files, type :TPCMD “REORG”
This command will initiate a job to clean up the Transporter files.
Wait for the message “Transporter Que Maintenance Done.”
3. Start up the Transporter using either the OPI command OPI TSTART
or type :TPSTART
Node File Maintenance
The Transporter Node File contains a list of valid Transporter destinations. As changes to
the DS network are made, these changes must be noted in the Node File residing on all
affected systems. For information regarding the use and setup of this file, refer to
Section I, Introduction and Setup.
Center for Information Services
-30-
April 2003
Section IV: Transporter System Internals
This section describes the six files and three programs that make up the Transporter
system.
Transporter Data Files
The Transporter system requires six data files. These files are all stored in the DATA
group of the TSS account.
TPQUE
This file is the Transporter request queue. It is an MPE KSAM file. To avoid a failure of
the Transporter system, this file must be periodically reorganized by using the INIT Q
command. If this file is destroyed, it may be rebuilt by running KSAMUTIL and issuing
the following command:
BUILD TPQUE;KEYFILE=TPQUEK;KEY=B,1,12;KEY=B,9,4;KEY=B,13,8,,DUP&;
KEY=B,21,8,,DUP;REC=-252,l,F,ASCII;DISC=2000,16,1
Then initialize with the INIT Q command of TPCMD.
The primary record key for the file is a composite data item composed of the queue
identifier (priority), the date the request was entered, the time the request was entered,
and a unique job ID number. Three alternate keys are supplied:
•
Job ID number
•
MPE Account Name of the requesting user
•
MPE User Name of the requesting user. For the COBOL record description of this
record see Figure 4.1 on page 33.
TPQUEK
This file is the KSAM key file for the TPQUE file.
TPHIST
This file is the Transporter request history file. All completed requests are deleted from
the request queue file and written to the history file. Additionally the records are written
to this file from Transporter systems running on other CPU's. These externally written
records can be identified by the value of “CX” in the Request Status (QFR-REQUESTSTATUS). To avoid failure of the Transporter system, this file should be cleaned of
records when the EOF is approaching the file limit size (usually 2000). If this file should
be destroyed, it may be rebuilt using the following MPE command:
BUILD TPHIST;REC=-252,1,F,ASCII;DISC=2000,32,1
This file uses the same record format as the TPQUE file (see Figure 4.1 on page 33).
Center for Information Services
-31-
April 2003
TPNODE
This file contains a list of valid destinations for the Transporter system. This file is an
unnumbered editor file (fixed length records, 72 characters long) in free-form format
with one record for each valid destination node. Each record contains four (4) data items
separated by commas. These items are, in order:
1. DSLINE name of the target node
2. Node Type or DSLINE name of an intermediate node
3. Node Group Number of one to three digits
4. Logon ID (including passwords) of the Transporter supervisor ID on the target
system. This ID is usually MGR.TSS but may be MANAGER.SYS or
OPERATOR.SYS.
If there is no Node Type or Intermediate Node, this should be indicated by a null entry
between two (2) commas in the location it would have normally appeared. Node Types
are:
HOME
This indicates the nodename of the user's own system.
TAPE
This indicates that the associated nodename is not available
through DNS/DS but through tape exchange only.
TPFCY
This file is a data file required for the Transporter mechanism to process PRINT requests.
This file supplies $STDIN information to the FCOPY program.
TPHELP
This file is the text file containing the HELP command information. It is a standard editor
file (including line numbers, which are stripped before the data is displayed).
Any information to be displayed can be entered in this file. But it should not contain
more information than will fit in the screen memory found on user terminals.
Center for Information Services
-32-
April 2003
Figure 4.1: Transporter System Queue File
Cobol Record Description
***
***
***
***
TRANSPORTER
COPY ELEMENT: CFDTPQUE
COBOL "FD” AND RECORD DESCRIPTION FOR TRANSPORTER
SYSTEM QUEUE FILE.
FD TRNSPRTR-QUE-FILE .
LABEL RECORDS ARE STANDARD DATA RECORD IS QUE-FILE-RECORD.
01 QUE-FILE-RECORD.
05 QFR-RECORO-KEY.
07 QFR-QUE-NUMBER
PIC X(2).
88 QFR-SYSTEM_QUE
VALUE “00”.
88 QFR-SUPERVISOR-QUE
VALUE “10”.
88 QFR-URGENT-QUE
VALUE “20”.
88 QFR-NORMAL-QUE
VALUE “30”.
88 QFR-LOW-QUE
VALUE “40”.
88 QFR-TAPEONLY-QUE
VALUE “80”.
88 QFR-GARBAGE-QUE
VALUE “99”.
88 QFR-OS-QUE
VALUE “XT.”
07 QFR-OATE
PIC S9(4) COMP.
07 QFR- TIME
PIC S9(8) COMP.
07 QFR-SERIAL-NUMBER
PIC 9(4).
07 QFR-ALTKEY-l
REDEFINES QFR-SERIALNUMBER.
09 FILLER
PIC X(4).
05 QFR-ALTKEY-2.
07 QFR-REQUEST-ACCOUNT
PIC X(8).
05 QFR-ALTKEY-3.
07 QFR-REQUEST-USER
PIC X(8).
05 QFR-REQUEST-TYPE
PIC X(2).
88 QFR-SEND-FILE
VALUE “SF”.
88 QFR-GET –FILE
VALUE “GF”.
88 QFR-PRINT-REQUEST
VALUE “PR” “PC”.
88 QFR-MSG-REQUEST
VALUE “MS”.
88 QFR-SHUTDOWN-REQUEST
VALUE “**”.
05 QFR-REQUEST-STATUS
PIC X(2).
88 QFR-REQ-PENDING
VALUE “ “ “WT”.
88 QFR-REQ-IN-PROGRESS
VALUE “IP”.
88 QFR-REQ-COMPLETE-DSN
VALUE “CD”.
88 QFR-REQ-COMPLETE-TAPE
VALUE “CT”.
88 QFR-REQ-DS
VALUE “CX”.
88 QFR-REQ-ERROR
VALUE “ER”.
88 QFR-LINE-ERROR
VALUE “LN”.
05 QFR-ERROR-CODE
PIC X(4).
05 QFR-TAPE-VSN
PIC X(6).
05 QFR-XMIT-5TART.
07 QFR-XSDATE
PIC S9(4) COMP.
07 QFR-XSTIME
PIC S9(8) COMP.
05 QFR-XMIT-END.
07
QFR-XEDATE
PIC S9(4) COMP.
07
QFR-XETIME
PIC 59(8) COMP.
05 QFR-FILE-SIZE
PIC 9(6).
05 QFR-LAST-RECORD-SENT
PIC 9(8) COMP.
05 QFR-RETRY-COUNT
PIC 9(4) COMP.
05 QFR-MESSAGE-INFO.
07 QFR-REQUEST-FILENAME
PIC X(40).
07 QFR-NEW-FILENAME
PIC X(40).
07 QFR-ENV-FILE
REDEFINES QFR-NEW-FIlENAME PIC X(40).
05 QFR-REMOTE-NODE
PIC X(8).
05 QFR-INTERMEDIATE-NODE
PIC X(8).
05 QFR-REMOTE-LOGON
PIC X(36).
Center for Information Services
-33-
April 2003
05
88
88
05
05
05
88
88
05
88
88
05
88
88
05
05
05
QFR-REPLACE-FLAG
QFR-NOREPLACE
QFR-REPLACE
QFR-INP-NUMBER
QFR-REQUEST-HANDlE
QFR-DEL-CODE
QFR-NODELETE
QFR-DELETE
QFR-RET-CODE
QFR-NORETRY
QFR-RETRY
QFR-REL-CODE
QFR-NORELEASE
QFR-RELEASE
QFR-ORIG-ERROR
QFR-STEP-NO
QFR-TFILE
Center for Information Services
PIC X(2).
VALUES"
""NO".
VALUE "RE".
PIC 9999.
PIC X(20).
PIC X.
VALUES" " "N".
VALUE "V".
PIC X.
VALUES" " "N".
VALUE "V".
PIC X.
VALUES" " "N".
VALUE "V".
PIC X(4).
PIC 59(4) COMPo
PIC X(8).
-34-
April 2003
Transporter Programs
The Transporter system is made up of three programs. These programs are stored in the
EXC group of the TSS account. Source files are in the SRC group. The Relocatable
library, RL.RL.TSS, is required to PREP all programs. All programs are written in
COBOLII. The Required Copy Library is TPCPLIB.SRC.TSS.
TPCMD (TP1003C)
This program is the command interface. It controls all functions of the Transporter
system and accepts requests for data transfer. It can be run as either interactive or batch
and will accept an INFO= string in the form of a single Transporter command to be
executed.
Additional PREP parameters: ;MAXDATA=20000;CAP=IA,BA,PM,MR
TPMON (TP1001C)
This program is the Transporter mechanism. It receives instructions from the command
interface (TPCMD) via the TPQUE queue file. Normally, one copy of the program is run
for each Node Group defined in the TPNODE file, but multiple copies are legal. The
TPMON program receives the number of the Node Group it is to act upon via the
PARM= parameter on the RUN MPE command. If this parameter is zero (0), the program
will ignore the Node Groups and process all requests.
Normally, this program is initiated by the STARTUP command of the TPCMD command
interface.
Additional PREP parameters: ;MAXDATA=20000;CAP=IA,BA,MR,PH_PM
TPSLV (TP1002C)
This program is the PTOP slave program that is activated on the target node computer by
the TPMON program on the local computer. It is used to supply the TPMON program
with the logon information for the target username, to send messages to the system
console on the target system, and to transfer records to the history file (TPHIST) on the
target system. .
Additional PREP parameters: ;MAXDATA=20000;CAP=IA,BA,PM
For an overview flowchart showing the interrelation of the files and programs in the
Transporter System, see Figure 4.2 on the following page.
Version numbers of all programs may be checked by using the following:
:RUN program;INFO=”*VERS"
Center for Information Services
-35-
April 2003
Center for Information Services
-36-
April 2003
Appendix A: Programmatic Access to Transporter
Transporter may be called from a user program using Process Handling. To do this, the
system intrinsics CREATE and ACTIVATE are used. The Transporter command is
passed to the command interface (TPCMD) via an INFO= string. In COBOLII the
following items or their equivalent must be included in the Working Storage Section:
77 TRANSPORTER-COMMAND
01
05
07
07
07
07
07
05
07
07
07
07
05
07
07
07
PIC X(80) VALUE SPACE.
CREATE-PARAMETERS.
ITEM-NUMBERS.
ITEM-2
ITEM-3
ITEM-ll
ITEM-12
ITEM-0
ITEM-LIST.
CRE-PARM
CRE-FlAGS
INFO-PTR
INFO-LENGTH
ITEM-ADDITIONAL.
ERRCD
PIN-NUMBER
RUN-NAME
PIC
PIC
PIC
PIC
PIC
S9(4)
59(4)
S9(4)
59(4)
59(4)
COMP
COMP
COMP
COMP
COMP
VALUE
VALUE
VALUE
VALUE
VALUE
2.
3
11
12.
0.
PIC
PIC
PIC
PIC
59(4)
59(4)
S9(4)
S9(4)
COMP
COMP
COMP
COMP
VALUE
VALUE
VALUE
VALUE
0.
1.
0.
0.
PIC S9(4) COMP VALUE 0.
PIC S9(4) COMP VALUE 0.
PIC X(I4) VALUE TPCMD.EXC.TSS”.
Note: TRANSPORTER-COMMAND may have a size up to PIC X(255); the VALUE
clause of INFO-LENGTH must be equal to the size of TRANSPORTER-COMMAND.
To call the Transporter command interface (in COBOLII), a character string in the form
of a valid Transporter command must be moved to TRANSPORTER-COMMAND (or
included as a VALUE clause). And the following statements or their equivalent must be
added to the source program at the point you want to call Transporter:
CAll INTRINSIC "LOC." USING @TRANSPORTER-COMMAND
GIVING INFO-PTR.
CALL INTRINSIC "CREATEPROCESS" USING ERRCD PIN-NUMBER
RUN-NAME ITEM-NUMBERS
ITEM-LIST.
CALL INTRINSIC "ACTIVATE" USING PIN-NUMBER \3\.
Detailed explanation of the CREATEPROCESS and ACTIVATE intrinsics can be found
in the MPE V Intrinsics Reference Manual. Explanation of the .LOC. pseudo-intrinsic is
in the COBOLII/3000 Reference Manual.
Center for Information Services
-37-
April 2003
This page inserted for back-to-back printing.
Center for Information Services
-38-
April 2003
Appendix B: Transporter Error Codes
The following error codes are valid only for Transporter version 7.0 and later.
Code
Source
Message
9001
TPMON
Error on rewriting queue entry to queue file.
9002
TPMON
Queue file record contains an invalid request type code.
9003
TPMON
Error deleting shutdown request from queue.
9004
TPMON
Error deleting queue file entry from queue.
9005
TPMON
Error on rewriting queue entry to queue file.
9006
TPMON
Request for remote system password failed due to PWRITE
error.
9007
TPMON
Request for remote system password failed due to PREAD
error.
9008
TPMON
Failure to activate PTOP slave program (POPEN error) .
9009
TPMON
Handshake with PTOP slave program failed due to PWRITE
error.
9010
TPMON
Handshake with PTOP slave program failed due to PREAD
error.
9011
TPMON
Handshake with prop slave program failed due version
number mismatch.
9012
TPMON
Transfer of remote command failed due to PWRITE error.
9013
TPMON
Invalid status record returned after remote command
execution (status flag1 not = 3).
9014
TPMON
Remote command execution failed, non zero condition code
returned.
9015
TPMON
Retrieval of status record failed due to PREAD error.
9016
TPMON
Transfer of status record failed due to PWRITE error.
9017
TPMON
Transfer of history record failed due to PWRITE error.
7001
TPMON
File label not read, file or PV does not exist.
7002
TPMON
File label not read, Group or User does not exist.
7003
TPMON
File label not read, Account does not exist.
7004
TPMON
File label not read, illegal file name.
7005
TPMON
File label not read, illegal Group or User name.
7006
TPMON
File label not read, illegal Account name.
Center for Information Services
-39-
April 2003
Code
7007
Source
TPMON
Message
File label not read, illegal request to DIR'READ.
7008
TPMON
File label not read, required parameter not passed to
DIR'READ
7009
TPMON
File label not read, hard error while reading file label
7010
TPMON
File label not read, soft error while reading file label.
Additional error codes may be found in the DS/3000 HP 3000 to HP 3000 Network
Administrator Manual (32185-90002), Appendix A (DS/3000 Errors). MPE Command
Interpreter error codes do not have a single reference source.
Center for Information Services
-40-
April 2003