An Undocumented APL2 AP

Transcribed from the printed issue; not yet reviewed. Read it in the PDF of the issue, page 112

We have long felt a need for a ‘bottom-up’ workspace-management tool, i.e. one that allows the administration team to look at what objects are in which workspaces. Up to now the only way to do this is to load individual workspaces (which can be a pain if the latent function calls up a full-screen dialog) and to list the objects from the workspace. What is needed is a single central workspace, whose tentacles can reach into all the other workspaces on the system and pull out the details of the global symbol table, and other information such as fix-times for functions and operators.

What follows has been derived in an afternoon’s doodling after a purely accidental decision to look at the functions in IBM’s supplied workspace 2 TSOIVP (installation verification program). This was followed up by looking at the code for AP104. After documenting the features I came across a paper [1] in which they are discussed, but a full description of the arguments and error codes is not given. So far this is the only documentation of AP104 I have been able to find.

Auxiliary Processor 104¶

Even though you are using Release 2 of IBM’s APL2 program product, you may not have heard of Auxiliary Processor 104. There is a good reason for this: IBM has not documented it. This is because it is only ‘temporary’ in the program product, and it may not be present in future releases.

I have not had too much time to play with it, but I have discovered the following about its operation. First of all set up a shared variable. A single variable is all that is required; any name will do, and it doesn’t need any initialization. Then set ‘commands’ into the shared variable, and obtain the results by referencing it. Commands must be simple character vectors, the results are nested vectors containing two numeric scalars (the minimum information returned) followed by one or more character vectors.

The following function sets up the shared variable the first time it is used, then leaves it in the workspace for use by future calls. As implied by its name it is only a test function, so don’t worry too much about lines 8 and 9.

     ∇TEST104 X;A
[1]   →(2=⎕SVO 'A104')/L2
[2]   A←104 ⎕SVO 'A104'
[3]   ⎕SVE←5
[4]   L1:→(2=⎕SVO 'A104')/L2
[5]   →(0≠⎕SVE)/L1
[6]   →0,⍴⎕←'Can''t share <A104> with AP104'
[7]   L2:A104←X
[8]   'Shape of reply is ',(⍕⍴A),', with lengths ',⍕⍴¨A←A104
[9]   A

Commands¶

The available commands are LIB and MLIB (which are followed by an optional library number) and LIST, MLIST, COPY, PCOPY and MCOPY. The parameters for the last group appear to be

• an optional global/local indicator (in parentheses)
• an optional library number
• a required workspace name
• an optional name class
• an optional ‘extra parameter’ which serves as a string of start-letters or a list of objects to be copied (delimited by spaces)

Defaults and Peculiarities¶

The global/local indicator is a G or L enclosed in parentheses. G indicates that we are only interested in global objects: L means we want localized objects, but this will only give a different result if the workspace contains suspended functions, and you only get the most local version of each object, including the globals if there isn’t a local version with the same name. If you omit this parameter, the AP assumes you want L. If you omit the library number the AP assumes you want to use your private library. If the name class is invalid it is ignored. If you specify a name class the processor will list or copy all objects of that name class that start with the first string of the ‘extra parameter’ (further strings are ignored). If you omit the name class the processor lists everything, or copies only those objects listed in the command. The start letters restrict the output. If you specify ABCD then you will get a list of objects whose names start with ABCD. If you specify start letters with an invalid name class or none at all the start letters are ignored for LIST or assumed to be the complete name of an object for COPY. If you do not give the ‘extra parameter’ the processor assumes that you want to list or copy everything. This processor uses lower-case letters rather than underscores (which for those of you familiar with auxiliary processor conversion options is the BCD or 370 option). You do not have any choice here! VSAPL groups are considered to be variables (as with those in APL2). Although the APL2 commands )COPY, )PCOPY and )MCOPY will copy groups if the name is enclosed in parentheses, AP104 will not do so. In fact, the parentheses will cause the command to fail with return codes 1 0 (some objects not copied). You can only copy system variables from VSAPL workspaces (i.e. with MCOPY, not with COPY or PCOPY). This mirrors the behaviour of the associated APL2 commands.

Examples¶

LIST (G) TEST

will list all of the variables, functions and operators in workspace TEST. No distinction is made between the different types of object in the listing.

COPY (G) 2345 TEST 3 DEF

copies all the global functions in workspace 2345 TEST that begin with the letters DEF.

Results¶

The returned data is a nested vector, the first two items of which are the return codes:

0 0

No error.

1 0

Some objects not copied

2 0

Don’t know

2 1

Invalid command passed to AP104

2 2

Library does not exist

2 3

Workspace not found. The specified name is expanded by the system to give the appropriate dataset name for a workspace (VSAPL, or APL2 private workspace or APL2 SAM library), or a search of the appropriate VSAM cluster is made (APL2 VSAM library). This error occurs if the dataset does not exist, or the workspace header is not found in the VSAM cluster, or items that do exist do not contain a valid workspace of the appropriate type. If you want to know what your system expects VSAPL workspaces to be called, enter )MCOPY TEST (where TEST is non-existent) and then enter )MORE immediately after the error message. APL2 tells you the name of the dataset it expects to find but can’t. On my system VSAPL datasets should be called <userid.@W.wsname>.

2 4

Workspace locked

2 5

Library not available

2 6

Library I/O error

2 7

System Limit

2 8

Don’t know for sure but it could be ‘Workspace is being used by somebody else, try later’

2 101

User aborted operation

2 102

Insufficient memory

2 103

Insufficient shared memory

2 104

Unexpected SVP error

2 105

Unexpected system error

2 106

Unexpected auxiliary processor error

3 0

Unmatched shared variable offer

If the error codes are other than 0 0 or 1 0 then only these two items will be present in the result vector. If COPY, PCOPY or MCOPY managed to copy everything you asked for then there should be only three items, otherwise there will be seven items, unused items being null. LIB and MLIB will give you four items. The extra items (beyond the second) are as follows:

The third element is always null with LIB and MLIB the workspace date-and-time saved with the others. The fourth element is always a list of workspaces with LIB and MLIB the requested list of objects with LIST, which will be null (we hope) if you ask for Global labels (name-class 1) (see later on) a list of objects requested but not found for COPY, PCOPY and MCOPY. The fifth item is a list of objects not copied (only applies to PCOPY, obviously). I have not got anything other than the null vector in items 6 and 7.

Lists of workspaces are returned as ‘a nine-column left-justified matrix of workspace names, ravelled’. Otherwise, all lists of objects are returned as vectors with the names separated by single spaces (and ending eith a space). These lists can, of course, be converted to vectors of vectors and matrices by means of DAN (IBM-supplied with associated processor 11) and disclose.

And finally¶

Be careful if you are COPYing a function and your workspace already contains a suspended function of the same name. As is documented for )IN, you do not get a state-indicator warning. Continued execution of the suspended function picks up the OLD function, any further reference to the function (even while the old one is still suspended) will pick up the NEW function. As I said, be careful!

Be careful if you use this AP in any case. Obviously IBM will not accept responsibility for anything that you might do, and nor will I. If you manage to find out more about this auxiliary processor then please let me or the editor know.

Does anybody out there know how to get Global Labels, deliberately rather than accidentally? What am I doing wrong? I seem to get them now and again in my workspaces for no good reason. Checking that )SI is clear, I enter quad-NL 1, and I get a list of items which, from my strictly-applied naming conventions can only have originated as statement labels from some function or other. Copying them into another named workspace or a clear workspace converts them into variables! What on earth is going on?!?!?

References¶

[1] Michael Deichmann: Hidden and missing features in APL2. (Maersk Data A/S, Copenhagen, Denmark, 21 October 1986). Mr Deichmann gives a brief application of the auxiliary processor in a workspace-management environment, and ends with a plea for this processor to be made more generally available. I wholeheartedly support this plea, but would also like to see extra features made available, such as the function-fix time mentioned in the first paragraph, above.