FSTM -- FORTRAN SubTask Manager ================================ FSTM is a number of routines which allow users to write programs which may initiate and control subtasks. A subtask is a timesharing task which is run by another ("parent") subtask. The user may, at his/her option, run subtasks synchronously -- only one task active at a time -- or asynchronously -- multiple tasks active. The parent task has the following capabilities over the subtask: Initiate subtasks Suspend subtasks Resume suspended subtasks Abort subtasks Send messages to a subtask Receive messages from a subtask Read task status Set tasks local event flags The subtask may: Suspend itself Send messages to the parent task Receive messages from the parent task Initiate subtasks of its own Each parent task may initiate multiple subtasks as shown below: TASK1 /\ / \ / \ TASK2 TASK3 /\ / \ / \ TASK4 TASK5 A parent task only has direct control over the tasks immediately beneath it on the tree, except that if any task in the tree is aborted, all tasks below it on the same branch are aborted. This does not, however, apply to suspension. This package also includes a routine to allow a task to chain to another task. When the task terminates, the program chains, and the parent task (if any) is notified that the subtask has chained. The successor then takes the place of the old subtask in the tree. Note that chaining takes place after termination so that all subtasks of the original task are terminated. It is not possible to pass a programs subtask onto its successor. ******************* NOTE *********************** As each task has a 32K size limit, subtasking has the potential of causing operations to grind to a halt if this facility is misused. All jobs requiring subtasking should first be examined for viable alternatives. If subtasking must be used, the program must be developed under the direction of a system programmer. Unauthorized subtasking is a violation of ICRCC policy, and will be dealt with summarily. FSTM Data Structures ==================== 1. Calling sequence. The final parameter in each subroutine call is an optional error block. If included, all errors which occur during the execution of the call will be reported to the user as described in section the next paragraph. If omitted, an error will cause a error message to be printed to the user terminal, and the FORTRAN traceback information. In most cases, the program will then be aborted with ERROR status. All other parameters, except where noted, are required, and must be included in the calling sequence. 2. Error status block. The error block in the subroutine calls consists of two words. The first word is the error flag word. If zero, no error has occurred. If negative, a TCS error has occurred and the second word is the error qualifier. If positive, an FSTM error has occured and the contents of the second word are meaningless. 3. Idents. The first parameter of all calls (except CHAIN) is the ident. This ident is assigned to all subtasks when they are initiated (by RUNST), and are used thereafter to refer to the subtasks. Occasionally, the ident may be used to refer to the parent task, or the predecessor task as follows: IDENT refers to ----- --------- -1 parent task 0 predecessor task(receive), or successor task(send) 1-n subtask (n is the maximum number of subtasks). 4. Messages. Tasks may send messages to either their successor, parent or to subtasks. Messages may be up to 253 characters. Messages are stored in the node pool and are charged against the sender's task. If many messages are to be sent without the receiver calling for them, the user may have to increase his/her node pool limit (consult task builder manual). When the receiver calls for the message, it is removed from the pool, and the nodes are freed for other use. Messages consist of a single word containing the number of bytes to follow, followed by the message itself. On receipt of the message, the first word is the number of bytes to follow. 5. Filenames. Two of the subroutines (CHAIN and RUNST) require filenames. These may be alphanumeric literals, or a byte string terminated by a null byte. THE USER MUST PRECEDE THE FILENAME SPECIFICATION WITH A BLANK CHARACTER. ie. CALL RUNST(' SUBTASK.TSK;3',IDENT) note the ---^---blank in front of the filename. If the device, unit, and/or UIC is omitted, the users default is assumed. If the filetype is omitted, .TSK is assumed. If the version number is omitted, the latest version will be used. FSTM Subroutine Description. ============================ 1. CHAIN -- Declare a successor task. CHAIN allows the user to declare a successor program and, optionally, send a message to that program. Calling CHAIN merely declares the successor and returns to the calling program. It is the programmers responsibility to exit. If the program terminates with successful (or no) status, the task declared is initiated. If the initiating program has sent a message, it will be instantly available to the successor. Calling sequence: CALL CHAIN(filename,message,error) filename is the filename as described in the previous section. message is the optional message to be sent to the successor. error is the optional error status block. 2. RUNST -- Initiate a subtask. RUNST allows the user to initiate a subtask, and, optionally, send a message to it. If the message is specified, it is guaranteed to be available when the subtask starts. If the task file does not exist, no error will be returned, but the system will type an INS FAILURE message. This will NOT abort the current task, however. Calling sequence: CALL RUNST(ident,filename,message,error) ident is the identifyer returned to the program In all calls, this subtask will be refered to by this identifier. filename is the filename as described in the previous section. message is the optional message to be sent to the subtask. error is the optional error status block. 3. ABRTST -- Abort a subtask. ABRTST allows the parent program to abort a subtask. Note that this routine cannot be used to abort the parent program. Calling sequence: CALL ABRTST(ident,error) ident is the identifier for this task. error is the optional error status block. 4. WEVNST -- Wait for subtask events. WEVNST allows the user to wait for a subtask event. A subtask event is one of the following: 1) Subtask has terminated, 2) Subtask has aborted, 3) Subtask failed to load, 4) Subtask has suspended itself, 5) Subtask has terminated and chained, 6) Task has sent a message. Calling sequence: CALL WEVNST(ident,error) task for which an event has occurred. ident is returned. This contains the ident of the subtask causing an event. This does not preclude the possibility that other subtasks have caused events. error is the optional error buffer. 5. RSTTST -- Read subtask status. RSTTST reads the status byte of a subtask. The status byte is cleared on reading, so entire byte should be decoded. If subtask has terminated, the user may call TERMST to get job termination information (see paragraph 6, below). Calling sequence: CALL RSTTST(ident,status,error) ident is ident of subtask to be queried. status returned status as follows: bit octal meaning --- ----- ------------------------ 0 1 Successfully terminated and chained. 2 4 Successfully terminated. 3 10 Aborted. 4 20 Load failure. 6 100 Task has sent message. 7 200 Task has suspended itself. error is the optional error buffer. 6. TERMST -- Get subtask termination status. TERMST allows the user to get more information on the tasks termination than that available from RSTTST. Unlike all the other subroutines, TERMST has no error buffer in the call, and no identifier. It always refers to the last task addresses by RSTTST which aborted (or did not load). Calling sequence: CALL TERMST(jobnam,jobsiz,jobtim,jobstt) jobnam returns a word containing three RAD50 characters defining the job number. This may by decoded using the R50ASC routine described in the FORTRAN IV Plus Users' Guide. jobsiz returns the size of the job in 32 word blocks. jobtim returns the CPU time of the job in ticks (usually, 1/60th second). jobstt returns the jobs exit status: -1 Job did not exit with status. 0 Job exit status WARNING. 1 Job exit status SUCCESS. 2 Job exit status ERROR. 4 Job exit status SEVERE ERROR. 7. SUSPST -- Suspend a subtask. SUSPST allows a parent task to suspend a subtask. This does not cause a task event, so the parent task should not wait for suspend status from this task. Calling sequence: CALL SUSPST(ident,error) ident is the subtask identifier. error is the optional error buffer. 8. RSUMST -- Resume a suspended subtask. RSUMST allows the parent task to resume a suspended subtask. Resuming a running task returns success status. Calling sequence: CALL RSUMST(ident,error) ident is the subtask identifier error is the optional error buffer 9. STEVST -- Set subtask event flag. STEVST allows the parent task to set a subtask's local event flag. Calling sequence: CALL STEVST(ident,efn,error) ident is the subtask identifier efn is the subtask event flag number. error is the optional error buffer. 10. SNDMES -- Send a message. SNDMES allows a task to send a message to: 1) a subtask 2) the parent task, or 3) the successor task. Calling sequence: CALL SNDMES(ident,message,error) ident is the subtask identifier, 0 for successor task, and -1 for parent task. message is the buffer containing the message. error is the optional error buffer. 11. RCVMES -- Receive a message. RCVMES allows a task to receive messages sent to it. The task has no control over who the message is from. There is also no facility for waiting until a message is available. Protocols should be designed to use event flags. Calling sequence: CALL RCVMES(ident,message,maxlen,error) ident is the identifier of the sender task: -2 No message available or defunct subtask. -1 Parent task 0 Predecessor task >0 Subtask identifier. message Buffer to receive message. If buffer overflow occurs, the byte count will be set to the actual number present, rather than the original message size. maxlen is the length, in bytes, of the message buffer (in- luding the byte count word as two bytes). error is the optional error buffer. If error(1) is set to 10, a buffer overflow has occurred, and excess data is ignored. FSTM Subroutine Size ==================== The amount of space added to a program by inclusion of these routines depends, of course, on the size of the TCS subroutines drawn from the system library. The discussion below describes only the size of the FORTRAN interface routines themselves. If any FSTM subroutines are included, the following modules will be loaded: NAME Size(decimal words) ---- ------------------- FSTM 210 .STER. 113 ------ --- total: 323 words In addition, each routine called will add: NAME Size(decimal words) ---- ------------------- RUNST 76 ABRTST 30 SUSPST 25 RSUMST 25 WEVNST 77 RCVMES 56 SNDMES 51 STEVST 28 CHAIN 61 RSTTST 71 If the entire set is loaded, this will add 823 words to your program (not including TCS subroutines from system library). These sizes apply to current versions as of the writing of this document, and may not remain accurate.