The SHARP APL S-task Interface

Richard H. Lathwell


An S-task is a SHARP APL task which obtains its input and delivers its output as character-vector values of a shared variable, but is otherwise identical to a T-task.


An S-task is a SHARP APL task which obtains its input and delivers its output as character-vector values of a shared variable, but is otherwise identical to a T-task. The S-task interface permits any program which is capable of communicating with the Sharp Shared-Variable Processor (i.e., any program which can share variables) to communicate with SHARP APL in the manner of a user at a terminal. This description of the S-task interface is from the point of view of APL programs; in order to prepare non-APL programs for this purpose, refer to SIN-48 SHARP APL Installation-written Auxiliary Processors, and to the DSECT TYIOMODE contained in the APE APL source libraries.

SHARP APL Processor Characteristics

In order to communicate with any processor with shared variables, a definition of its characteristics is required. To this end, the SHARP APL Processor is designed to behave as follows:

•   A line of input or output consists of a sequence of APL characters.
•   The APL Processor waits for a single line of input.
•   The line of input is processed and results in an arbitrary number of lines of output, but no fewer than one.
•   The final line of output is an input prompt which contains an indication that the APL Processor is waiting for input.

Establishing an S-task

When SHARP APL has been installed with appropriate configuration parameters, it connects itself to the shared variable processor as processor 1. An S-task may then be created by offering to share a variable with processor 1:

   1 ⎕svo 'name'

where name is a vector of 15 or fewer characters denoting the name of a variable to be used for the interface. The account which offers the variable to processor-1 is known as the initiator of the S-task. When resources permit, the S-task controller will allocate the necessary tables, obtain a clear workspace, assign a task identification number, and then match the offer to share. When the degree of coupling becomes 2, the task is in the same state as a T-task after a terminal has become connected to the system, but before the user has signed on.

The normal system limits on the number of tasks which can be created by a single user also apply to S-tasks; if the total number of tasks signed on with the initiator’s account number has reached this limit, a new offer to processor 1 will be ignored, and the variable must be re-offered after the number of tasks has been reduced. The initiator of an S-task is analogous to the initiator of an N-task in that the S-task may be terminated at any time by a ⎕bounce .

Communication with an S-task

S-task input and output is in the form of APL character vectors of four or more elements. The first four characters of each value contain control information which must be present. The first two of these characters are not used at the present time, and must be binary zeroes, i.e., ⎕av[0 0] . (Note: index origin 0 is assumed throughout this discussion.) The third element is used to denote commands to the S-task controller from the initiator and responses from the S-task controller (see below); ⎕av[0] in this position indicates that the value is to be passed on to APL. The fourth element is used to indicate the meaning of the value which is being passed from SHARP APL to the initiator.

For example, the first input to an S-task will normally be an attempt to sign on to SHARP APL:

   name←⎕av[0 0 0 0],')1234:key'

Assuming that the account number and key are valid, the response returned in name will be:

   prefix,'2134)22.13.00 04/01/80 sueblue'

i.e. the normal indication of a successful signon. Otherwise the response might be:

   prefix,'incorrect signon'


   prefix,'number not in system'

The important point to note is that, for every value set in the interface variable, APL or the S-task controller will respond with one or more values in reply.

APL Output Blocking

While APL sends output a line at a time, the S-task controller will catenate several lines together in order to reduce the number of shared variable accesses required. Each line is preceded by two characters which define the length of the line including the two length characters. Each line must be “deblocked” by a code segment such as the following:

   read:→(0<⍴block)/take       ⍝ branch if block contains lines
     block←name                ⍝ receive output from APL
   take:k←256⊥⎕av⍳2↑block      ⍝ length of next line
     output←2↓k↑block          ⍝ next line
     block←k↓block             ⍝ drop line from block

Qualification of Values Received from APL

The fourth element of prefixes received from APL indicates the meaning of the rest of the vector. Common combinations are shown in figure 1.



then the elements of mode have the following meaning when their values are 1:

mode[0] -   The S-task workspace is in immediate execution mode, i.e., is in a state where system commands will be recognized and processed. The purpose of this signal is so that initiator programs can provide “system commands” of their own: when this mode element is 1, input lines with a right parenthesis as the first non-blank character can safely be intercepted by the initiator.
mode[1] -   The rest of the line contains an obfuscating blot to obscure passwords, etc. The blot can consists of more than one line.
mode[2] -   The S-task is not signed on to SHARP APL.
mode[3] -   A keyboard-locked terminal is ready for input.
mode[4] -   APL wishes the terminal cursor or carrier reset to the left margin of a new line. This may be received following a break signal.
mode[5] -   The vector containing arbitrary output from ⎕arbin or ⎕arbout . This will occur alone when more arbitrary output will follow, and with mode[6] or mode[7] for the final block of a ⎕arbin prompt or ⎕arbout data respectively.
mode[6] -   The vector is a prompt for input: SHARP APL expects input after this output. Normally, the input will be catenated with this prompt by the initiator, and returned to APL. However, the initiator may instead process the prompt in conjunction with additional input, and return the processed information to APL.
mode[7] -   The value is output, and more output will follow.

Control Characters

Certain character values have meanings of a control nature when passed to or from APL as normal input or output. Common control characters are:

crlf ⎕av[156]   Carriage return/linefeed. Advance the medium to a new line with the carriage or cursor positioned at the left margin. APL regards the crlf character as an “end of input” marker, and it does not examine characters which follow it.
lf ⎕av[159]   Linefeed. Advance the medium to a new line without repositioning the cursor or carriage.
bs ⎕av[158]   Backspace. Reposition the cursor one position to the left.
tab ⎕av[2]     Tabulation. Never included in the S-task output. When included with the S-task input, tab will be evaluated with respect to ⎕ht .
eob ⎕av[157]   End-of-block. This character commonly occurs in S-task output for historical reasons. It has no meaning and should be ignored when it occurs in normal output.

S-task Controller Commands

The third element of values set by the initiator is a command to the S-task controller as follows:

⎕av[0] -   indicates the character vector is APL input.
⎕av[1] -   is a request for accounting information. The response from the S-task controller is a three-element integer vector containing 3↑⎕ai of the S-task. If the S-task is not signed on to APL all three elements will be zero.
⎕av[2] -   is a request to signal BREAK, analogous to depressing the BREAK key on a terminal connected to a T-task.
⎕av[3] -   is a request for disconnect permission, which allows the initiator to retract the interface variable without immediately terminating the S-task. If permission has not been requested, retracting the variable will result in the immediate termination of the S-task in a manner similar to the termination of a T-task when the telecommunication line is disconnected. After retraction, the interface variable remains as an offer from processor 1 to the initiator; resharing resets the permission to retract. The S-task terminates if it requests input while the variable retracted.
⎕av[4] -   is a request to reset the retraction permission obtained previously by ⎕av[3] .

S-task Controller Responses

The S-task controller responds to each non-zero command (except for accounting information which returns an integer vector) with a four-element character vector (preceded by a two-character length) whose third element indicates the result of the command:

⎕av[0] -   indicates the command was successfully executed.
⎕av[1] -   indicates an invalid value: an invalid command value, non-character value, non-vector value, or a character vector of fewer than four elements.
⎕av[2] -   indicates that APL could not accept input because of insufficient workspace.
⎕av[3] -   indicates that the S-task controller refused to honour a request because the S-task was not signed on to SHARP APL.

S-task Termination

An S-task will be terminated by any of the following:

•   ⎕bounce
•   Sending a valid signoff command, e.g., )off  when mode[0] is 1.
•   Retracting the interface variable, e.g. ⎕svr 'name'  without disconnect permission.
•   A request by the S-task for input while the interface variable is retracted with disconnect permission.

Figure 1: Typical Model Combinations

                        Mode Index

  x       Occurs with all modes when the S-task is not signed on to APL.
        x Normal output.
       x  Normal input.
x      x  Immediate execution prompt.
   x    x KB locked terminal ready for input. Input prompt will be emitted upon receipt of “break” signal.
xx     x  Input prompt text is a blot.
 x      x Output text is a partial blot.
      x x arbout final sequence.
      x   arbout — more to follow.
      xx  arbin input prompt.
     x  x APL requests cursor at the left margin, new line.

First appeared as SHARP APL Technical Note 39, The SHARP APL S-task Interface, 1981-06-01.

created:  2012-09-27 09:45
updated:2012-09-27 16:10