1 PAM ----- The Subsystem provides three PAM routines, used by programs to acquire parameters of types %string, %integer and %longreal. In calling a PAM routine, the command describes the parameter it requires and nominates a variable to receive the given value. A call is made for each parameter in turn, the order of call determining the order in which they are expected from the user. No failure flag is returned to the command by any of the PAM routines. If a parameter is faulty, i.e. does not satisfy the qualifier in the vector supplied to the PAM routine, and the parameters are being acquired by prompting, the user will receive an error message and be prompted for a correct value. The three PAM routines share a standard format: (PAM vector, local variable) Contents Page 1.1 Typical PAM calls 1 1.2 The PAM vector 2 1.3 Getting a string parameter 6 1.4 Getting an integer parameter 8 1.5 Getting a long real parameter 10 1.6 Additional PAM routines 11 1.1 Typical PAM calls --------------------- Here are examples of calls for the most commonly required parameters. 1. emas3integer("Input;route,char,in;?;The file to be processed", %c inchan) returns a channel number associated with the file specified by the user, which can be used in an IMP select input statement or a Fortran READ statement. The PAM vector calls for a file which must exist, and have filetype "character"; the name of the file is not returned, only the channel number used to read it. The "?" in the vector indicates that no default value is specified. 2. emas3integer("Output;route,char,out;.out;". %c "The output file or device", outchan) prompts the user for an output file or device. obtains a free channel number, DEFINEs that channel to refer to that channel, and returns the chaanel number, ready for a "select output" or other write-operation in variable OUTCHAN. The char tag is an extra check that if there is an existing file of the specified name with a filetype other than character, it will not be overwritten. The tag data can replace char where appropriate. The default value specified, .out, causes output to be directed to the terminal if no parameter is specified by the user. 3. emas3string("File;fileormem,read,char;?;The file of records", fname) returns the full name of a file, or member of a partitioned file, checked for read access permission and filetype "character". This contrasts with the previous examples where a channel number is returned. 4. emas3string("Outfile;file,write;xreport;The report file", freport) returns a filename (xreport by default) for which write access is required. 5. emas3string("Operation;word,make,replace,append", ops) returns a string containing one of the three words specified. In this example no default is defined. The user can specify an abbreviated form of the word, so long as no ambiguity results. Hence the value m would match make. Matching is insensitive to the case of the letters of the words in the vector and of the word typed by the user. The matched word is returned to the command in upper case. 6. emas3integer("Operation;word,make,replace,append;make", opi) returns an integer value, 0 for make, 1 for replace and 2 for append depending on which the user specifies. In this case make is nominated as the default if the user does not specify a value. 1.2 The PAM vector ------------------ As described ealier, the command writer describes the parameters the command requires by specifying a PAM vector for each. On each call of a PAM routine, the associated vector governs the behaviour of PAM in acquiring a value for the parameter. The PAM vector is encoded as a text string with up to five fields: prompt; qualifier; default; help; keyword The fields are described below. Contents Page 1.2.1 Prompt field 3 1.2.2 Qualifier field 3 1.2.3 Default field 3 1.2.4 Help field 4 1.2.5 Keyword field 5 1.2.6 Missing PAM vector fields 5 1.2.1 Prompt field ------------------ The prompt field is displayed to the user when PAM requests input from the terminal for a parameter. This occurs when: - the user fails to supply a value on the command line for a mandatory parameter (i.e. one with no default); - the user explicitly requests prompting by calling the command with the single parameter "?" or "??". The first word of the last line of the prompt is taken as the parameter's keyword, used where the form of call keyword=value is employed. If the prompt field contains a newline, then the first time it is issued the whole text is displayed, but subsequently only the last line is given. 1.2.2 Qualifier field --------------------- The qualifier field is particularly important. It indicates which values are acceptable for the parameter. This enables checks to be made on file and device names; on filetype, access permission and existence; or, for integer values, checks on specific values or ranges of values. The qualifier can be extended by appending tags to indicate additional checks. For example, the qualifier file may be made to check that the file exists by adding the appropriate tag: file,exist. As an alternative to the set of built-in qualifiers, you can nominate your own checking routine to perform non-standard checks; this is described in the EMAS-3 Users' Guide. 1.2.3 Default field ------------------- If the command writer provides a value in the default field, then this is returned when the user does not offer a value. If the parameter is mandatory, then the default field should contain "?" to indicate that no default is available. When a user is prompted for a parameter and a default is available, it is shown in brackets: Continue(yes): Where the user omits a parameter and a default is available, then normally occasionally desirable to have a parameter behave like a mandatory parameter while nevertheless possessing a default value. The effect is that a prompt is issued if no value is specified. The user can indicate acceptance of the default by pressing in response to the prompt. This conditional defaulting is selected by enclosing the default field in parentheses: "Input file;file;(t&list);some help" If a null value is acceptable for a parameter, the tag ornull should be given. If, in addition, the default value is itself null, this should be explicitly shown: "Output;file,ornull;;some help" In response to a prompt, a null value can be typed as "". This may occasionally be useful when a null value is acceptable for a parameter, but a non-null default is defined for it. 1.2.4 Help field ---------------- The help field is displayed when the user replies "?" in response to a prompt. Newlines may be included in the text of the field. An alternative to supplying the text of the help information explicitly, is to nominate a helpfile for the command. Indeed, this is the required method of providing help information about the whole command, when the user requests this by entering the single parameter "??". A helpfile is a character file constructed as a VIEW file (see User Note 9). One helpfile may contain entries for several commands, with a "view section" for each. Within the section describing each command, there should be a subsection for each of its parameters. The help text for the ACCEPT command is as follows: ! ! !> To designate a helpfile, the text of the help field should appear in the following form within the vector: call pamhelp(ercc90:myhelpfile) In general, a helpfile need only be specified in the vector of the first PAM routine call made by a command. Its value is remembered for all subsequent PAM routine calls made for the command. For a command with no parameters, no PAM routine call is made and therefore no help field is defined. The procedure EMAS3 HELPINFO provides an alternative method of conveying a help field to PAM. The help field given is used only if the user requests help about the command by calling it with the special parameter "??". The specification of the routine is: %external %routine %spec EMAS3 HELPINFO(%string %name HELP FIELD) It is also possible to nominate your own help routine to supply the necessary information: see chapter 18 of the EMAS-3 Users' Guide. 1.2.5 Keyword field ------------------- The keyword of a parameter is taken from the first word (of the last line) of the prompt field. Exceptionally, where this value is unsuitable, an additional field can be appended to the PAM vector, following the help field and separated from it by a semicolon, to define the keyword. For example: "File;fileormem;?;The type4 entries;type4" 1.2.6 Missing PAM vector fields ------------------------------- If a field is omitted from the PAM vector, a value is allocated as follows: prompt is set to Integer (or String or Long Real, depending on the name of the PAM routine called) qualifier is set to any default is set to ? (i.e. no default) help is set to the qualifier field. 1.3 Getting a string parameter ------------------------------ The routine for obtaining the value of a string parameter is EMAS3 STRING. Its specification is: %external %routine %spec EMAS3 STRING(%string %name VECTOR, VALUE) Contents Page 1.3.1 Qualifier 6 1.3.2 Tags for string qualifiers 7 1.3.1 Qualifier --------------- The qualifier field in the vector is used to determine whether the parameter value supplied by the user is valid. The possible qualifiers are: qualifier valid values any any non-empty string group a syntactically correct group name fileormem a syntactically correct file or pdfile member name file a syntactically correct file name fileordev a file name or a network device name user the name of a registered user device a device name filelist one fileormem, or several joined by '+' signs date a date, in the format dd/mm/yy word,text0,text1,text2,... the parameter supplied is compared with text0, text1, etc. If an unambiguous match is found, ignoring case and spaces, the matching text in the qualifier is returned. For example, given the qualifier word,no,yes a parameter value of ye would yield the result YES. The result is returned in upper case. A null value is defined by making one of the text options null, e.g. word,,yes,no. lcword,text0,text1,text2,.. operates like word except that the result is returned in lower case. 1.3.2 Tags for string qualifiers -------------------------------- Qualifiers may be modified by tags. Tags follow the qualifier and are separated from it, and from each other, by commas. String parameters are normally returned in upper case with spaces removed. This can be varied by use of the following tags: verbatim the result has case and spaces preserved lc the result is returned in lower case. The secret tag is provided to hide confidential information, such as a password parameter retrieved by using the qualifier any. secret the effect of this tag varies according to how the parameter was acquired. If it was presented at Command level, then the value is removed from the recall file. If prompted for then echoing is turned off. For files, pdfile members and groups, the existence of the object and access permissions to it are checked by the following tags: exist the file, member or group must exist notexist the file, member or group must not exist read read access must have been permitted (implies exist) write write access must be allowed (if the file exists). The following tags apply a filetype check to a file or member, if the file or member exists. In themselves, they do not imply an exist check. object an object file nonst a non-standard file (not object, char, data or pdfile) char a character file data a data file pdfile a partitioned data file dir a directory file (associating entry names with object file names). If none of these tags is set, the parameter is merely checked for correct syntax. The join tag applies to the filelist qualifier only: join concatenates the component files to a temporary file whose name is returned. If only a single file is specified, no copy is made of it. Only character files may be joined. All parameters are subject to ampersand expansion. To forbid this, the following tag is used: noamp the parameter does not permit ampersand expansion. All file, member and group parameters are subject to wild-card expansion This can be controlled by the following tags: nowild the parameter does not allow wild-card expansion cowild if a wild-card expression is given for this parameter, then all other parameters with tag cowild require a corresponding wild-card expression. Certain standard parameter values may be acceptable even though the value supplied does not pass the check implied by the qualifier, for example: file,orequals any,ornull These parameters are catered for by the following tags: ornull a null value is acceptable orequals a value of "=" is acceptable or.all a value of .ALL is acceptable or.end a value of .END is acceptable or.null a value of .NULL is acceptable. When parameters are supplied on the same line as the command, the command history scheme stores them along with the command name. By contrast, parameters acquired by prompting are not stored as part of command history. By including a tag history in the first PAM call, you can indicate that the parameters prompted for are to be added to the command history record. 1.4 Getting an integer parameter -------------------------------- If the user is required to supply an integer value for a parameter, then the command writer should use the PAM routine EMAS3 INTEGER to retrieve it. However, if the outcome of a PAM check on a string value is most naturally represented as an integer, then EMAS3 INTEGER should again be used. For example, a parameter might have three valid values, YES, NO, DONTKNOW. By using EMAS3 INTEGER and setting up the qualifier part of the vector appropriately, the command writer can make PAM check for these values and return 0, 1 or 2 respectively. See the qualifier word, below, for details. Another situation where EMAS3 INTEGER is appropriate is in the setting up of a route (in EMAS 2900 terminology, defining a file or device). When the user supplies a file name or device name, EMAS3 INTEGER can check the validity of this parameter and return a channel number, which the command could then select for input or output. See the qualifier route, below, for details. The specification for EMAS3 INTEGER is: %external %routine %spec EMAS3 INTEGER(%string %name VECTOR, %integer %name VALUE) Contents Page 1.4.1 Qualifier 9 1.4.2 Tags for the route qualifier 9 1.4.1 Qualifier --------------- The qualifier in the vector is used to determine whether the parameter value supplied by the user is valid. The possible qualifiers are as follows: qualifier valid value any any integer value m:n a range of numbers. m and n are the bounds; a null value means no lower (or upper) bound; for example 6:10 means a number between 6 and 10 3: means a number greater than or equal to 3 :3 means a number less than or equal to 3 a sequence of ranges or values in numerical order for example 0:3,5,8,10:12 means 0,1,2,3,5,8,10,11 or 12 A null value is permitted by adding a tag of the form null=value. value is returned as the result if no parameter is supplied. word,text0,text1,text2,... the parameter supplied is compared with text0, text1, etc. If a text matches the parameter value or starts with the parameter value, ignoring letter case, then the index of the text is returned. For example, given the qualifier word,no,yes a parameter value of N or NO or n etc. would give 0, while y or ye or yes would give 1. A null value is defined by making one of the text options null, e.g. word,no,yes,. route a file or pdfile member name, or a device name. 1.4.2 Tags for the route qualifier ---------------------------------- A number of tags are provided to modify the operation of the route qualifier. Tags follow the qualifier and are separated by commas. As described above, the route qualifier allows the user to specify a file or device name. PAM associates this with a channel number which it returns to the command as an integer value. This may be used in a subsequent call of an IMP SELECT INPUT or SELECT OUTPUT or a Fortran READ or WRITE statement. The normal procedure is to allow PAM to choose a free channel number. It is possible, however, to preset a fixed channel number in the VALUE parameter of EMAS3 INTEGER, and indicate this by use of the following tag: preset the file or device is associated with the channel number given in the VALUE parameter Additional checks are performed when a tag is included which indicates whether the route is to be used for input or output: in the file or device is to be used for input. Hence a check is made that either a valid input device, or an existing file with read access permitted, is specified. out the file or device is to be used for output. A check is made that either a valid output device, or a filename which can be written to, is specified. The file need not exist, in which case it must be possible to create it; if it does exist, however, it must have write access permitted. If the file does exist, an additional check can be made on its filetype to prevent an attempt to read from a file of the wrong type, or to overwrite an existing file of a different type. char a character file data a data file object an object file nonst a non-standard file (mapped file). Additional tags can be used to specify further details of the file definition. They have the same effect as the similarly named parameters of the DEFINE command. size= kb where kb is a number in the range 1 to maxfilesize, giving the maximum allowed size for the (output) file Vn defines V record format with a maximum of n bytes per record Fn defines F record format with n bytes per record C defines a character file (for Fortran only). 1.5 Getting a long real parameter --------------------------------- The routine for obtaining the value of a long real parameter is EMAS3 LONG REAL. Its specification is: %external %routine %spec EMAS3 LONG REAL %c (%string %name VECTOR, %long %real %name VALUE) The only qualifier provided is any. 1.6 Additional PAM routines --------------------------- A number of routines are provided to enable a command to perform manipulation of the command line: - %external %routine EMAS3 GETRESTOFLINE(%string %name LINE) returns the list of parameters remaining on the line, or the complete parameter line if none have been read yet. The routine is not destructive, and can be followed by calls of EMAS3 STRING or EMAS3 INTEGER as required. - %external %routine EMAS3 LINE(%string %name LINE) again returns the remainder of the parameter line, but clears it in addition. - %external %routine EMAS3 LCLINE(%string %name LINE) operates like EMAS3 LINE, but returns the parameter line in the same form as specified by the user. Hence spaces and case are preserved. - %external %routine EMAS3 SETLINE(%string %name LINE) sets the value of the current parameter line. - %external %routine EMAS3 LASTPARAM(%string %name PARAM) returns the most recently acquired parameter in the form of an uninterpreted string. If the previous PAM routine acquired an integer parameter with qualifier route, then EMAS3 LASTPARAM would return a string containing the file or device name specified by the user. If the previous routine called for a string with qualifier filelist,join, which returns the name of a temporary concatenated file, then EMAS3 LASTPARAM would return the original filelist parameter value. The routines can be used to preview the parameters before formally acquiring them. The preview may be required to guide the subsequent parameter acquisition process. Alternatively, the parameter line may be amended, and additional parameters added, before EMAS3 SETLINE is used to put it back in place. Finally, the standard PAM routines are called to acquire each parameter in turn.