The MYOPTIONSUPPORT entry points MYOPTION, ANY_MYOPTIONS, INSTALLATION_OPTIONS, and LIBRARY_OPTIONS are implemented in GENERALSUPPORT. These entry points provide a convenient and consistent method for users and sites to specify preferences for programs.
Users store their preferences in their CANDE/MYOPTIONS file. Sites can store their preferences in *INSTALLATION/OPTIONS either on the same pack as the client program or on the same pack specified for GENERALSUPPORT in the SL (Support Library) system command. These files are plain text files (for example, TEXTDATA, SEQDATA) created and updated using a system editor.
| Note: | Ensure that the security attributes of *INSTALLATION/OPTIONS allow all users read access to the file. |
The preferences are keyed to the client programs, where each client uses a different key. Sometimes the key matches the name of the client. For example, the EMAIL utility uses the key EMAIL. Keys are composed of letters (case sensitive), numbers, and the special characters “/” and “_”.
Each record in the CANDE/MYOPTIONS or INSTALLATION/OPTIONS file contains the client key (or the universal key, “*”) optionally followed by a name, a separator (either “=” or “:”) and the text as shown below. Each client specifies its own key and interpretation of the remaining information. See the Help text of each client (for example, EMAIL).
──┬─ * ───┬─┬────────┬─┬─ = ─┬─<text>──────────────────────────────────┤ └─<key>─┘ └─<name>─┘ └─ : ─┘
The client passes its key to the Boolean procedures ANY_MYOPTIONS and INSTALLATION_OPTIONS, which return TRUE if there are any matches to that key or the universal key “*”. The procedures also return the matching records, in the array parameters.
The Boolean function MYOPTION retrieves the value of a specified preference from an option array. It has two array parameters. In the first parameter (CMD), the caller places the name of the preference option to be located. If that option is found, MYOPTION replaces CMD array contents with the value of the preference option and the MYOPTION function result is set to TRUE. The second parameter (OPTIONS), is the options array to be searched. It must have been previously obtained from ANY_MYOPTIONS or INSTALLATION_OPTIONS. If the specified preference name is not found, MYOPTION returns the value FALSE.
The preferences recognized by each client vary, as does the syntax, and should be fully documented in the client Help text. By convention, the universal keys are used to specify the user's name, location, e-mail address, and so forth. The keyed preferences can be used to specify default options, specify options to be used when none are specified, define new options (in terms of existing options), set up file equates, and specify default values.
Within a preference file, records whose last nonblank character is “%” are automatically continued with the next record.
Occasionally, a user or site might need to maintain multiple options files. For example, a user mght change his FAMILY based on the work he is doing. Alternatively, a user might want to use a different set of options based on the terminal he is using.
MYOPTIONSSUPPORT provides a method for redirecting (based on STATIONNAME) the options file. Records at the beginning of an options file that contain a “#” in the first column are redirection records. The “#” is followed by 0 or more nodes of a STATIONNAME, an “=”, and a file title. When MYOPTIONSUPPORT accesses an options file, it looks for a redirection record that matches the current STATIONNAME. If a match is found, MYOPTIONSUPPORT uses the designated options file. See the examples below.
Examples
The following is an example of a CANDE/MYOPTIONS file:
*NAME=Alice Doe
*ROOM=C233
*DEPARTMENT=My Department
*SSN = 123-45-6789
*EMAIL=AliceDoe@wonderland.com
EDIT EDITOR=*SYSTEM/EDITOR ON NEWRELEASES
EDIT TYPE=ALGOL
EMAIL MAIL: BCC, LOGIN="myusercode"/"mypassword", SIG=%
"THIS COMMUNICATION MAY CONTAIN CONFIDENTIAL AND/OR OTHERWISE %
PROPRIETARY MATERIAL and is thus for use only by the intended %
recipient. If you received this in error, please contact the %
sender & delete the e-mail and its attachments from all computers."
EMAIL NEWS: SIG="Disclaimer: Opinions are personal and do not speak %
for Our Company
EMAIL ERIK=ErikJones@hiscompany.com
EMAIL ETEAM=#ERIK, "Mark Smith" MarkSmith@ivyleague.edu
EMAIL SUPPORT=My.Contact@unisys.com
HELP: BROWSE, BUFFER=2100, STATUSLINE OFF
HELP NULL: TOPICS={PROGRAM, USAGE, EXAMPLES}, BROWSE OFFIf a user runs at more than one host, he can use the following single record CANDE/MYOPTIONS file on the second host:
#=(MY)CANDE/MYOPTIONS ON MYPACK AT MYHOST
For example, if a user wants to use a different CANDE/MYOPTIONS when running from STATIONNAME MY/HOME, the following record can be inserted at the beginning of the CANDE/MYOPTIONS file:
#MY/HOME=CANDE/MYOPTIONS/24X80
The following is an example of an *INSTALLATION/OPTIONS file:
*COMPANY=Our Company *DEPARTMENT=Our Department *BUILDING=Our Building *ADDRESS=125 Main Street; Anytown, USA 12345 EMAIL MAILSERVER=server1.mycompany.com EMAIL ALTMAILSERVER=server2.mycompany.com,server3.mycompany.com EMAIL NEWSSERVER=123.45.678.9 EMAIL ALTNEWSSERVER=123.45.678.90 HELP TEXTBOOK=SYMBOL ON DOC HELP PATH=SYMBOL, *SYMBOL ON DOC, *SYMBOL/41 ON DOC, % *SYMBOL/40 ON DOC, *SYMBOL/39 ON DOC, *SYMBOL/38 ON DOC, % *SYMBOL/37 ON DOC, *SYMBOL ON DISK;% BOOK, *BOOK ON DISK, *BOOK ON NI00, (MAIL)BOOK ON ADMIN
If the site administrator installs the *INSTALLATION/OPTIONS file on the same pack as GENERALSUPPORT, specified by using the SL system command, the following single record *INSTALLATION/OPTIONS ON TESTPACK can be used to eliminate the need to update multiple files when changes are made to the *INSTALLATION/OPTIONS file. Note that GENERALSUPPORT is sometimes specified to HLPACK or TESTPACK.
#=*INSTALLATION/OPTIONS ON HLPACK
The following is an example for a MYOPTIONSUPPORT client.
When writing a client, use the following templates to declare the entry points:
LIBRARY MYOPTIONSUPPORT (LIBACCESS = BYFUNCTION,
FUNCTIONNAME = "GENERALSUPPORT.");
BOOLEAN PROCEDURE INSTALLATION_OPTIONS (OPTIONS); ARRAY OPTIONS [*];
LIBRARY MYOPTIONSUPPORT;
BOOLEAN PROCEDURE LIBRARY_OPTIONS (MYNAME, OPTIONS);
EBCDIC ARRAY MYNAME [*];
ARRAY OPTIONS [*]
LIBRARY MYOPTIONSUPPORT;
BOOLEAN PROCEDURE ANY_MYOPTIONS (OPTIONS); ARRAY OPTIONS [*];
LIBRARY MYOPTIONSUPPORT;
BOOLEAN PROCEDURE MYOPTION (CMD, OPTIONS); ARRAY CMD, OPTIONS [*];
LIBRARY MYOPTIONSUPPORT;
ARRAY MYOPTIONS, INSTALLED_OPTIONS [0:31];
EBCDIC ARRAY MYNAME [0:255];
BOOLEAN ANY_OPTIONS, INSTALLED;The declarations INSTALLATION_OPTIONS, INSTALLED_OPTIONS, and INSTALLED, as well as the code referencing them, can be omitted when the client is interested only in user preferences and not site preferences.
Use the following code (replacing “key” with the client key) to read the preference files:
REPLACE INSTALLED_OPTIONS BY "key" 48"00"; INSTALLED := INSTALLATION_OPTIONS (INSTALLED_OPTIONS); REPLACE MYOPTIONS BY "key" 48"00"; ANY_OPTIONS := ANY_MYOPTIONS (MYOPTIONS);
If the client is itself a library and needs to search for the *INSTALLATION/OPTIONS file after the file freezes, it should use LIBRARY_OPTIONS instead of INSTALLATION_OPTIONS as in the following example:
REPLACE MYNAME BY MYSELF.NAME; FREEZE(PERMANENT); INSTALLED := LIBRARY_OPTIONS(MYNAME, INSTALLED_OPTIONS);
The following declarations and code searches the preferences:
DEFINE CAND (A, B) = (IF (A) THEN (B) ELSE FALSE)#,
COR (A, B) = (IF (A) THEN TRUE ELSE (B))#; ARRAY NAME, DEFAULT, NULL, EQUATE [0:31]; POINTER P;
REPLACE NAME BY "*NAME=" 48"00"; IF CAND(ANY_OPTIONS, MYOPTION(NAME, MYOPTIONS)) THEN % If TRUE, NAME contains the null terminated name % e.g. Alice Doe 48"00"
REPLACE EQUATE BY "EDITOR=" 48"00";
IF NOT F.FILEEQUATED THEN
IF COR(CAND(ANY_OPTIONS, MYOPTION(EQUATE, MYOPTIONS)),
CAND(INSTALLED, MYOPTION(EQUATE, INSTALLED_OPTIONS))) THEN BEGIN SCAN P:EQUATE UNTIL = 0; REPLACE P BY "."; REPLACE F.TITLE BY EQUATE; END;
REPLACE DEFAULT BY ":" 48"00"; IF CAND(ANY_OPTIONS, MYOPTION(DEFAULT, MYOPTIONS)) THEN OPTIONS (DEFAULT);
IF INP = ":" THEN BEGIN SCAN INP:INP+1 WHILE = " "; OPTIONS (INP); END ELSE BEGIN REPLACE NULL BY "NULL:" 48"00"; IF CAND(ANY_OPTIONS, MYOPTION(NULL, MYOPTIONS)) THEN OPTIONS (NULL); END;
