SND - Send/Receive Packets Program ================================== Users' Guide ============ 1. Introduction ================ This task is a generalised Send/Receive Data Utility, for use on RSX-11M systems. To use this task, the following directives (selectable during SYSGEN) must be available:- Receive data AST support Send/Receive data directives Mark-Time directives Get task parameters Get LUN information During initialisation, each of these directives is issued. Some are required to obtain information to initialise the task identification display, and some directives are tested in order to determine if the host executive supports the required facilities. If any of these directives fail, then the following message is displayed on the TI: device and execution is terminated:- SND -- *FATAL* - RSX-11M EMPT REQUEST FAILURE The basic configuration of this task has a total of 16 packet buffers available. These buffers are separated into 2 groups of 8 Receive buffers and 8 Send buffers, identified by the characters 'R' and 'S' respectively. Within each group the buffers are identified by a single alpha character being A,B,C,D,E,F,G, and H. A task name list is also provided, which always caters for a number of task names that is equal to the total number of packet buffers available, being 16 in the basic configuration. Should a change in these figures ever be required, then the number of packet buffers should always be increased or decreased by integral units of 4. The size of all other internal list structures is governed by the number of packet buffers available. 2. Command Line for Operation ============================== This task is known to the system as 'SND.TSK' and may be invoked by a 'RUN $...' command, by its task name 'SND' or as an 'MCR' function. If it is not invoked as an 'MCR' routine, its first action is to display the task parameters identifying the current task image. These parameters define-: The task image name The task priority The partition The run-time user identification code (UIC) The LUN count of all LUN's available to the task The TI: device identification The total number of packet buffers available The Send/Receive buffer identification letters The standard prompt for the program is:- SND> to which switches should be entered as described in Section 3. Note that it is possible to change this prompt by means of the /ID switch (3.4.2) so as to allow multiple versions of SND to run from one terminal without confusion. 3. Function Commands ==================== Function commands cause 'SND' to perform specific actions. These commands are supplied in response to the task's prompt 'SND>'. All but one of the available functions are defined by a switch, which may have optional parameters. A command is a series of switches terminated by a comma (,), an equals (=) or a carriage return (). Multiple commands may be supplied in one command line and cannot follow an equals (=). The edit request function must always be the only function in a command, and it must be the last or only command in a command line. Numeric values supplied in a command or as parameters to a switch are converted with an octal default. Switch parameters may be specified as decimal by terminating the value with a decimal point. Typing control Z (^Z) causes SND to terminate and also invokes the function '/CL' to flush the task's receive queue. 3.1 ENTERING TASK NAMES IN THE TASK NAME LIST This command takes the following format:- TKn:=x..... This function is the only one which is not defined as a switch. It is always the first function processed during the execution of a command. The value of 'n' determines the task list entry that begins the task name set up. A number of task names can be supplied in one command line, each task name is separated from the next by a comma (,), the last task name is terminated by carriage return (). Two consecutive commas define a null task name and will cause the appropriate entry in the task name list to be cleared. Task names are entered into the list sequentially from the defined entry. The default entry identifier is zero (0). The legal range of 'n' is 0 to 17 octal (2 *(Total number of packet buffers) -1). 3.2 INITIALIZING FOR REPEAT OPERATIONS These functions are executed once for each command and before the repeat processing is begun. Once set, these functions remain in effect for the entire processing of the command. 3.2.1 Send to Defined Task (/TS:n) Data packets are sent to the task named in the task list, whose task list entry number is given by 'n' (Default = 0). The range of 'n' is the same as the range defined for entering task names in the task name list (0 to 17 octal). 3.2.2 Receive from Defined Task (/TR:n) Data packets are received from the named task in the task list whose task list entry number is given by 'n' (default=0). The range of 'n' is the same as the range defined for entering task names in the task name list (0 to 17 octal). 3.2.3 Send to and Receive from this Task Image (/IM) Data packets are sent to the sending task and are received only from the receiving task. Thus, the current image of 'SND' will send packets to itself and receive only its own packets. This function over-rides '/TS' and '/TR'. 3.2.4 Send to Named Task (/PS:task) Data packets are sent to the task identified as the parameter in the switch. This task name is a temporary task name and is discarded after command processing is complete. This function over-rides '/IM' and '/TS' for send operations. 3.2.5 Receive from Named Task (/PR:task) Data packets are received only from the task identified as the parameter in the switch. This task name is a temporary task name and is discarded after command processing is complete. This function over-rides '/TR' and '/IM' for receive operations. 3.3 REPEATABLE OPERATIONS These functions are repeatable and are described in their order of execution. 3.3.1 Mark Time (/WT:T:M:A) This function performs a delay for a defined period. Although this is the first of the repeatable functions to be processed, its point of execution depends upon the parameters supplied. The command parameters are:- T = Units of delay T = Clock ticks S = Seconds M = Minutes M = Magnitude of delay A = Point of delay C = Before executing repeat functions S = Before sending each data packet R = Before receiving each data packet P = Combines S and R 3.3.2 Send a Packet from a Receive Buffer (/RC:list) A data packet is sent from a data packet receive buffer. This function allows received packets to be forwarded to another task. The parameter defines a list of receive buffers from which a packet is to be sent. A maximum of 'n' receive buffers can be specified, where 'n' is the total number of receive buffers available. A buffer may be specified more than once in the parameter specification. The default parameter is the single buffer identified as 'A'. 3.3.3 Send a Packet from a Send Buffer (/SN:list) This function causes packets to be dispatched from a send buffer. The parameter defines a list of send buffers. A maximum of 'n' send buffers can be specified, where 'n' is the total number of send buffers available. A buffer may be specified more than once in the parameter specification. The default buffer identification is 'A'. 3.3.4 Dequeue a Packet (/DQ:list) A data packet is received into a receive buffer. The parameter defines a list of receive buffers. A maximum of 'n' buffers can be specified, where 'n' is the total number of receive buffers available. As with '/RC' and '/SN', a buffer may be specified more than once in the parameter list. The default buffer identification is 'A'. 3.3.5 Repeat for all Defined Task Names (/AL) This function repeats all the repeatable functions for all tasks defined in the task name list. If either of the functions '/IM' or '/PR' are present in the command, then the first task name in the task name list (TL0:) is effectively replaced by the name implied or specified by the additional switch. The task name defined in TK0: is not used or changed by this function. 3.3.6 Repeat Operations (/RP:n) All repeatable operations are repeated 'n' times. The legal range of 'n' is 1 to 99, the default value is 1. The two functions '/RP' and '/AL' should be used with care, since the total repeat count is 'n' * 'the number of task names defined'. Thus if 8 'send' packets, 8 'receive' packets, and a full task name list (containing 20 task names) and a maximum repeat count is specified, then the number of packets that will be sent is:- (8 + 8)*20 *99 = 31680 This is the maximum number of packets that can be sent. From this example it can be seen that the dynamic storge region can be easily and quickly consumed. Each data packet requires 18 words of the RSX-11M Dynamic Storage Region (DSR) whilst residing in a task receive queue. 3.3.7 Activate Task (/RQ:par:pri:grp:own) This function is performed only once for each task specified in the repeat sequence. No distinction is made between sending and receiving task names, except that a temporary receive task name is not used. With this function, it is possible for programs to be activated without having to perform any associated send or receive functions. The specified task is activated at the end of the first repeat operation for that task. The parameters to this function apply to every task that is specified in the operation and cannot be varied within a command. Defaults apply to each of the parameters and are only changed if specified by the user. The parameters are defined below and the default settings are enclosed in brackets. par - Partition name (GEN) pri - Task's run priority (50.) grp - Group UIC (200) own - Owner UIC (200) 3.4 AUXILIARY FUNCTIONS The functions contained in this section are executed after the repeatable operations have been completed. They are listed in their order of execution. 3.4.1 Flush the Receive Queue (/CL:task) This function de-queues all queued packets. They are received into a temporary buffer which is not available to the user and are effectively lost. If any packets are de-queued, then the number of packets flushed from the queue is repoted. If a task name is supplied as the parameter then only packets that have originated from the named task will be flushed from the queue. All remaining packets, if any, will remain queued to this image of SND. 3.4.2 Changing the Prompt (/ID) This function alters the prompting sequence of 'SND'. The function may be negated by repeating the function in another command, which defines the default prompts. The default function prompt is 'SND>' and the default edit prompt is '*'. The prompts are appended to the installed task name of the current image of 'SND'.Thus if the task name of 'SND' is 'XXX...', then the extended function prompt becomes:- 'XXX...SND>' and the extended edit prompt becomes:- 'XXX...*' 3.4.3 List and Status Reports (/LI:type) The requested list or report is displayed on the TI: device. The parameter defines the option required, the default is 'ALL'. ALL - Display all lists and status reports. ID - Display task identification parameters. TSK - Display all task names in the task name list. PKT - Display the packet usage statistics, consisting of the buffer type and ID, the task name associated with the last send or receive opertion and the total send and receives performed using the idenfitied buffer. 3.5 EDIT REQUEST (/ED:tx) This function must always be the only function in a command which must be the last or only command in a command line. The function changes the operation of 'SND' from function command processing to edit command processing. A particular packet can be selected to be available for editing on entry to edit mode by supplying the packet buffer identification as the parameter to the switch. The buffer identification consists of the buffer type, which must be one of the following two characters:- S = Send buffer R = Receive buffer and the buffer reference, which is any one of the reference letters defined in the task identification parameters. The default packet buffer that is selected is 'send buffer A' (SA). 4. Edit Commands ================== Edit commands are used to examine, change or set single locations within a packet or an entire packet buffer. The user has a variety of options available for performing edit functions on the data area of the packet buffers. The packet buffer headers can only be examined in the format defined by RSX-11M. A packet header is the first two words of a buffer, which holds the name of the task associated with the last send or receive operation performed using the buffer. The task name is held as 6 Radix-50 characters. The user can select the data access mode as words or bytes. In addition the data type can be set to ASCII, Octal or Radix-50. A byte data access mode does not affect the output when the data type is ASCII or Radix-50. However, a byte data access mode does affect ASCII and Octal input. ASCII output is formatted to ensure that the characters can be displayed on the TI: device successfully. Control characters (0 - 37) are displayed as their upper case alpha equivalent preceded by an up-arrow (^). Lower case characters (140 to 177) (including delete) are displayed as their upper case alpha equivalent preceded by a percent (%). All numeric values supplied in edit mode are considered to be octal values. It is not possible to alter the radix of the supplied values in the command. The control Z (^Z) terminating sequence is not permitted in edit mode and is ignored. 4.1 DUMPING A PACKET Packets are dumped in the selected data mode in words or bytes. Radix-50 and ASCII dumps are not affected by the access mode. The packets are dumped, 4 words per line, irrespective of the access mode. Each line is preceded by the packet buffer identification and the octal offset of the first word in the line from the start of the packet data area. A dump is requested by a single character command. The following commands are accepted:- A - Dump in ASCII O - Dump in Octal R - Dump in Radix-50 4.2 SETTING A SINGLE LOCATION A single word or byte may be set with the appropriate data type. The command has the following format:- The data type defines the format of the data to be inserted. The data type is the same as defined for Packet Dumping (See 4.1). The offset is the octal offset of the location to be set, and is always a byte offset. The access mode defines whether bytes or words are to be addressed. If a space character is suplied, the access mode used is the current access mode. Byte access mode can be selected by typing a back slash (\) and word access mode is selected by typing a slash (/). The first 3 parts of the command define the location that is to be set and the data type that is to be used when interpreting the value. If byte mode is selected with ASCII, only the first data character is used. However, with the Octal data type, a conversion is performed and the last set of digits converted which fill the addressed location are used. With a Radix-50 data type a word is always set, the access mode serves only to change the default. In this case the offset must be word aligned. Word operations must always have even packet offsets. 4.3 SEQUENTIAL LOCATION EDIT This is a special edit mode which allows the user to step through the packet location in ascending order, optional- ly altering the location contents according to the se- lected data access mode. The command format is:- I The offset must always be an octal word offset. The legal data access modes are the same as specified in Section 5.2., while the data type can be any one of the 3 legal modes defined in Section 5.1. Each word of the packet is displayed according to the data type, preceded by the packet identifier and the byte offset from the start of the packet data area. The same restrictions apply for this function as are defined for setting a single location (Section 5.2). However, if byte mode is selected, then the values supplied by the user to set the word must be separated by a comma. The first value sets the low byte and the next value sets the high byte. Typing altmode (escape) causes the sequential location edit to be terminated. The sequence will also be terminated when the end of the packet buffer is reached. 4.4 SETTING THE MASK WORD The mask word allows the user to fill all locations in a packet buffer with a predefined value. The operation of this command is identical to the operations described in Section 5.3. The mask location can be opened for edit with the following command:- M 4.5 USING THE MASK WORD Having set the mask, the user may set a series of packet buffer locations with the value defined in the mask. The format of the command is:- F The offset is the word or byte offset from the start of the packet data area, and the access mode is the same as defined in Section 4.2 The repeat count defines the number of word or byte locations to be set in the packet buffer. It should be noted, that if byte access mode is used, then the packet locations are set from the low byte of the mask word. 4.6 USING THE NULL MASK This function enables a packet buffer to be cleared. The functionality of this operation is the same as that for using the mask word. The null mask word is always binary zero. The command format for this operation is:- Z 4.7 SELECTING A PACKET FOR EDIT A packet buffer may be selected for edit operations without returning to the function command level. The command takes the following format:- S The packet type can be either of the following characters:- S = Send buffer R = Receive buffer The particular buffer is selected by an alpha character being defined as the packet buffer identification in the task parameter display. The packet buffer identifications are A,B,C,D,E,F,G, and H in the basic task configuration. 4.8 IDENTIFYING THE CURRENT PACKET With this command, the user can identify the current packet that has been selected for edit and obtain the packet buffer header which is the name of the task associated with the last send or receive operation. The command consists of the single letter 'L'. The packet type and buffer identification are listed, and if available the associated task name. 4.9 PACKET COPYING This function enables a series of words or bytes to be copied from one packet buffer to another. Using this function does not alter the current packet. The format of the command is:- C= The destination and source packets are identified by their packet types, buffer identification and octal location offset. The access mode is specified as defined in Section 4.2 and the offset must correspond to the selected access mode. The repeat value defines the number of words or bytes to copy. The resulting offsets (initial offset + repeat) must not exceed the respective packet buffer limits. 4.10 TERMINATING EDIT MODE Edit mode can only be terminated by typing the single character 'X'. Control Z (^Z) is ignored if typed in Edit Mode. Typing the character 'X' returns the user to function command processing. 4.11 CHANGING TO BYTE ACCESS MODE With this command, the user can set the data access mode by typing the single character 'B'. This function enables the user to obtain byte formatted dumps without having to execute a command to change the access mode. 4.12 CHANGING TO WORD ACCESS MODE This command causes the data access mode to be set to words, and is specified by the single character 'W'. 5. Error and Information Messages All messages displayed by 'SND' are directed to the TI: device. If an error occurs during command line processing, then the command line processing is terminated at the point of the error and the remainder of the command line is lost. The following messages can be displayed by 'SND'. 5.1 SND--*FATAL* RSX-11M EMPT REQUEST FAILURE This message will be displayed if, during initialisation one of the required executive service requests failed. The user should check that the host executive supports the functions required by 'SND'. This utility cannot run without executive support of its required directives and task execution terminates. 5.2 SND--NO DATA PACKET(S) QUEUED A request to receive a data packet into a receive buffer failed because no packets were present in the tasks' receive queue. 5.3 SND--DATA PACKET(S) QUEUED One or more data packets hve been sent to this task. The packets will remain in the receive queue until they are explicitly de-queued by the '/DQ' or '/CL' functions. 5.4 SND--n PACKET(S) FLUSHED FROM QUEUE This message is displayed in response to the '/CL' function or on task exit but only if packets were queued to this task. The value of 'n' defines the number of packets that were de-queued. 5.5 SND-- x - DIRECTIVE ERROR = n During command execution a directive error occurred. The symbol 'x' identifies the directive as SND = Send data RCV = Receive data MRK = Mark-time RQS = Request task The value of 'n' (a signed decimal number) defines the directive error code returned. 5.6 SND -- COMMAND SYNTAX ERROR = n During command decoding, an error was detected in the command. The remaining unprocessed function command string is ignored. If the error ocurred in an edit command, then the request is not executed. The value of 'n' defines the cause of the error. The following error codes can be returned to the user. 1 Invalid command format/unrecognised command 2 Command parsing error 3 Edit request must be the only function in a command. 4 Edit request must be the last command in a command line. 5 Invalid mark-time parameters 6 Invalid list or status display parameters 7 Invalid packet buffer type 8 Invalid packet buffer identification 9 Invalid repeat range 10 Invalid task name entry request 11 Invalid task name list entry number 12 Task names specification invalid 13 Invalid data access mode 14 Invalid data type 15 Invalid packet offset/repeat count 16 Invalid task request parameters SND - Send/Receive Packets Program ================================== System Guide ============ This utility is structured with a data area and code area defined under one program segment. The code area is further sub-divided into initialisation code, function command processing code and edit command processing code. The data area contains fixed data, text strings and command parsing tables. When program initialisation is complete, the initialisation code area is cleared and allocated to the packet buffers and the task name list. This procedure reduces the effective size of the task image (Currently 4K). A small iterative section of code performs the allocation of the initialisation code to the data packet buffers and the task name list. This section of code is then used in the task as a general work area and for receiving unwanted packets via the '/CL' function (section 2.4.1). Initialisation is performed by requesting each of the following directives:- SRDA$ - Receive data AST GTSK$ - Get task parameters GLUN$ - Get LUN parameters MRKT$ - Marktime If any of these directives fail a fatal error is declared and execution is terminated. The directives GTSK$ and GLUN$ are required to obtain data for the task identification parameter display. Function commands are processed with the aid of the command string interpreter routines, which imposes the structure and format of the commands available to the user. However, edit commands are procesed using internal command parsing routines. Edit command processing permits only one edit function in a command line. This simplifies user operations and also the parsing routines and tables. In addition, command size limits (number of characters) are imposed on the edit commands. Thus a command will be rejected if it exceeds the maximum number of character permitted for that command. Only one TI: input buffer is allocated within the task. This buffer caters for a maximum command line size of 132 characters. It is used by the function, edit and data input routines, and is cleared before prompting on the TI: device. For this reason, edit mode cannot be entered during the parsing of a function command line. The task image of SND has two logical unit numbers assigned. The first one (LUN 1) is used for the TI: device input and output. The second one (LUN 2) is reserved for future enhancements. This task uses a receive data AST for notification of a packet which has been sent to it. The executive queues a receive data AST when a packet is sent to the task. No further receiee data AST's are queued for the task until the first AST queued has been serviced (see RSX-11M Executive Reference Manual for SRDA$). There is not therefore a one to one correspondence between data packets being queued and receive data AST's being queued. For this reason, SND is not able to count the number of packets in it's receive queue. When the receive data AST is executed, a flag is set causing an information message to be output before the function prompt.This flag remains set until the receive queue is cleared. When messages or prompts are output and that output fails, SND will ignore the I/O request. An input command error which is a function of the I/O communications will cause SND to terminate. A task activation request or send data request that fails due to lack of space in the Dynamic Storage Region (DSR) will cause SND to attempt to clear the receive queue to release some DSR storage. SND is a non-privileged task with a taskname of ...SND that uses two units (both assigned to TI:) and a stack of 64. There is also an optional global patch which must be made if you want the space character (octal 40) to be included in the Radix-50 character set - GBLPAT=SND:$CAT+50:1405. If control Z (^Z) is required for task termination in response to function, edit and data prompts then the following TKB patch should be applied - GBLPAT=SND:CTLZ:240:240:240.