If more than one copy of MARC is active at a time, a directive might be required to process two or more requests at the same time. If the directive code might have difficulty operating in this multiuser environment, limit the number of MARC worker stacks. On the P screen of the COMS Utility, set to 1 the number of maximum copies of MARC.
When you execute the DIRECTIVE command, MARC links by title to an external library that contains an entry point named-or exported as-EXTERNALCOMMAND.
Entry points must be defined in an ALGOL procedure that adheres to the following format:
Parameters
INTEGER PROCEDURE EXTERNALCOMMAND(
COMS HEADER ,COMMAND
% COMS HEADER ARRAY
% TEXT AFTER DIRECTIVE
,TAG % SECURITY, LANGUAGE
,DIRECTIVE % COMMAND PREFIX
,GET_DIALOG_ATTRIBUTE % DIALOG ATTRIBUTE PROC ,RESPONSE_FORMATTER % RETURN RESPONSE PROC
,SCRATCH % SCRATCH EBCDIC ARRAY
) ;
REAL ARRAY COMS_HEADER[*];
REAL ARRAY COMMAND[*];
REAL ARRAY TAG[*];
REAL ARRAY DIRECTIVE[*];
INTEGER PROCEDURE GET_DIALOG_ATTRIBUTE(ATTNO,ATT);
VALUE ATTNO;
INTEGER ATTNO;
REAL ARRAY ATT[*];
FORMAL;
INTEGER PROCEDURE RESPONSE FORMATTER(TEXT_LENGTH,TEXT);
VALUE TEXT_LENGTH;
INTEGER TEXT_LENGTH;
EBCDIC ARRAY TEXT[*];
FORMAL;
EBCDIC ARRAY SCRATCH[*];
The ALGOL library procedure EXTERNALCOMMAND uses the following parameters:
• COMS HEADER
• COMMAND
• TAG
Creating Custom Versions of MARC
• SCRATCH
These parameters are explained in the following paragraphs. See "Procedure Result" later in this section for an explanation of the values returned by the EXTERNALCOMMAND library procedure.
COMS HEADER Parameter
This parameter is the COMS header array given to MARC by COMS. User processing items can change or add to information in this array, making access to this information desirable-or even necessary-for some sites. The format of this array is described in the A Series Communications Management System (CaMS) Programming Guide.
COMMAND Parameter
This parameter is an array that contains any text specified after the directive, with leading and trailing blanks deleted. The first word of this array contains the length of the EBCDIC text that begins in the second word. This text is deliberately kept distinct from the directive itself. In addition, this parameter can be used to return a user-created command. See the explanation for value 4 under "Procedure Result"
later in this section.
For example, suppose a user enters MYCOMMAND ABCDE either through a MARC menugraph selection or directly in the Action field. COMMAND contains the value 5 in the first word and the character string ABCDE, in EBCDIC, beginning in the second word (the seventh character).
TAG Parameter
This parameter is an array that contains the following specific information about the calling dialogue:
• TAG [0]
Contains security information about the calling dialogues - specifically, information representing the security state of the calling dialogue at the instant of the call-as follows:
[03:01]
[02:01]
[01:01]
[00:01]
• TAG [1]
1 means COMMANDCAPABLE capability.
1 means SYSTEM USER capability.
1 means PRIVILEGED capability.
1 means COMS CONTROL capability.
Contains the length of the language attribute value (string) for this dialogue.
• TAG [2]
Contains the value of the language attribute (string). The length of the string is found in TAG[l].
Creating Custom Versions of MARC
DIRECTIVE Parameter
This parameter is an array that contains the names of the directives entered by the user. This parameter is deliberately separated from the command text. The first word of the array contains the length of the name. The name, in EBCDIC, begins in the second word (the seventh character) of the array.
GET DIALOG ATTRIBUTE Parameter -
-This parameter is a procedure that can be called within the EXTERNALCOMMAND library procedure to obtain additional information about the MARC dialogue that called the EXTERNALCOMMAND procedure. A predefined MARC dialogue attribute number is passed as the first parameter (ATTNO). If the attribute is within the range of known attributes and information about the attribute of this procedure exists, this procedure returns a result value of zero, and the current value of the attribute is returned in the array parameter (ATT).
Table 8-2 lists the result values of the GET_ATTRIBUTE procedure.
Table 8-2. GET ATTRIBUTE Procedure Result Values
Value Meaning
o The attribute information is valid.
1 There is no error, but the attribute information is null or undefined.
-1 The attribute number is out of range.
Table 8-3 lists the dialogue attribute numbers and the corresponding formats of the result in the array parameter.
Table 8-3. GET ATTRIBUTE Procedure Result Formats
Value ATTNO Result Format
o Caller identification. MARC stores the value 1 in the first word of the array parameter. This attribute permits use of this entry point by other software that can identify itself separately.
1 The current message control system (MCS) number of COMS as defined by the Network Definition Language II (NOLI/). This value is returned in the first word of the array parameter.
2 The MARC session LANGUAGE attribute for this dialogue. The length of
Creating Custom Versions of MARC
Table 8-3. GET_ATTRIBUTE Procedure Result Formats (cant.)
Value ATTNO Result Format
3 The version, cycle, and patch numbers of the calling MARC. Words 0, 1, and 2 contain the version, cycle, and patch number (as defined by the COMPILETIME intrinsic in ALGOl), respectively.
4 The usercode for this dialogue. The length of the usercode is in the first
6 The chargecode for this dialogue. If a chargecode is set for this session, the length of the chargecode is placed in the first word of the array and the
9 The value of the JOBSUMMARY attribute for the current session of this MARC dialogue. This value is returned in the first word of the array.
10
11
12
The current value of the JOBSUMMARYTITLE attribute of this MARC dialogue. This value is returned in the second word of the array with the length of the value in the first word. If no JOBSUMMARYTITLE is set, the first word of the array contains 0 and the procedure returns an ATT value of 1.
The value of the PRINTDEFAULTS attribute for this MARC dialogue. This value is returned starting in the second word of the array, with the length of the value in the first word. If no PRINTDEFAULT value has been set, the first word of the array contains 0 and the procedure returns an ATT value of 1.
The value of the NOJOBSUMMARYIO attribute for the current session of this MARC dialogue. If the attribute is FALSE, the first word of the array contains O. If the attribute is TRUE, the first word contains 1.
continued
Creating Custom Versions of MARC
Table 8-3. GET_ATTRIBUTE Procedure Result Formats (cent.)
Value AllNO Result Format
13 The current value of the DESTNAME attribute for this MARC dialogue. This value is returned in EBCDIC, starting in the second word of the array, with the length of the value in the first word. If no DESTNAME is set, the first word of the array contains 0 and the procedure returns an ATT value of 1.
14 The station name of this MARC dialogue. This value is returned in EBCDIC, starting in the second word of the array, with the length of the station name in the first word.
15 The CONVENTION attribute for this dialogue. The length of this attribute is returned in the first word of the array. The value of the attribute is returned in EBCDIC, beginning in the second word.
RES.PONSE FORMATTER Parameter
This parameter is a formal procedure that is called by the EXTERNALCOMMAND library procedure once for each line of the response to be returned to MARC for communication to the user. Characters such as carriage return and line feed characters can be embedded within text to produce multiple lines of output in one call to the RESPONSE_FORMATTER procedure.
This procedure has two parameters of its own: TEXT LENGTH and TEXT. The TEXT_LENGTH parameter represents the number of characters of text, and the text itself is contained in the TEXT parameter-the second parameter. The TEXT_LENGTH parameter must be no more than 255 characters; if it is, only the first 255 characters of the text are used.
MARC formats lines exceeding the screen width to avoid truncation of the output text.
The procedure returns a value of 1 if MARC determines that formatting is necessary for one of the following reasons:
• The message is longer than the screen width.
• The message contains characters with values less than an EBCDIC space (hexadecimal40) that would result in multiple lines of output.
In all other cases the result is O.
SCRATCH Parameter
This parameter is a scratch array for use by the EXTERNALCOMMAND library procedure. This parameter minimizes the need for the library to perform buffer
Creating Custom Versions of MARC
initialized by the library when needed rather than resized or deallocated. MARC does not clear this array before calling the library entry point.