****************************************************************** * * * SCIP/Campus Computing Facility * * Stanford University * * Stanford, Ca. 94305 * * * * (c)Copyright 1978 by the Board of Trustees of the * * Leland Stanford Junior University * * All rights reserved * * Printed in the United States of America * * * ******************************************************************
This manual is a functional description of ORVYL, the timesharing monitor developed by Stanford University, as seen by the terminal user and programmer.
- Chapter 1 gives a general overview of ORVYL.
- Chapter 2 is a description of the ORVYL file system and the command language file controls available to you.
- Chapter 3 describes LINK processing and control of your program execution under ORVYL.
- Chapter 4 details the command language debugging and program event recording aids available to the ORVYL programmer.
- Chapter 5 explains the ORVYL supervisor services and the ORVYL macro language. Macro instructions available to the programmer at the assembly language level are organized by management areas.
- Chapter 6 gives information about URAM, the Unified Record Access Method.
- Chapter 7 describes VAM/370, the ORVYL File Batch Access Method.
ORVYL is the product of a number of years of development of timesharing resources on IBM hardware at Stanford. From its introduction in the late sixties as a timesharing monitor on an IBM 9672, ORVYL has become a powerful timesharing system, taking full advantage of expanded OS/390 hardware capabilities. ORVYL currently operates under OS/MVS on IBM 9672 hardware. In conjunction with the WYLBUR= text-editing and remote job entry systems and MILTEN terminal communication systems, ORVYL provides the capability of executing user programs in an interactive environment. ORVYL brings a number of useful facilities to interactive programming:
- A command language providing file manipulation capabilities, program execution controls, and a debugging capability.
- A means of access to reentrant compilers and data base management systems called shared programs, allowing simultaneous processing by many users.
- An independent file system which employs special file security and file sharing controls.
- A program interface with WYLBUR allowing convenient use of available interactive system resources.
At the assembly language level, ORVYL also provides a number of program management services for your programs and subprocessors:
- Input and output processing macros permitting communication between your program, the terminal, ORVYL files, and the WYLBUR active file.
- General interrupt facilities allowing your program to control input/ output processing and utilize the hardware timer interrupt facilities.
- Miscellaneous supervisor services, such as reporting the date and time of day and memory management.
ORVYL maintains a file system independent from that administered under OS/MVS. The ORVYL file system provides file protection and sharing capabilities uniquely suited to the timesharing environment. Specific levels of access to particular files or all files created by you may be extended to other specified users or to a general class called PUBLIC. Files may be designated for concurrent use by many potential users or temporarily reserved by a single user for development or updating. A largely transparent interface between ORVYL files and the WYLBUR active file provides an efficient text-editing capability and a direct method for the loading of program object modules maintained in the OS/MVS file system. User files and the indexes required to access user files are maintained on disk. All disk allocation information, as well as file access information, is also retained on disk. The ORVYL file system maintains the following information, organized by user id and by file, on the file system catalog:
- By user id:
- account;
- number of ORVYL blocks currently in use in all files;
- maximum number of ORVYL blocks which may be allocated;
- PUBLIC class access privileges;
- privileges for other groups;
- privileges for individual users.
- By file:
- file name;
- number of ORVYL blocks currently in use in the file;
- PUBLIC class access privileges;
- privileges for other groups;
- file privileges for individual users.
ORVYL was first designed by Roger Fajman and, under the direction of Rod Fredrickson, implemented at the Campus Facility of the Stanford Computation Center in 1968. John Borgelt developed the original ORVYL file system. In 1971, a means for batch access to the ORVYL file system (VAM) was designed by Richard Levitt and later enhanced by Carol Lennox. Throughout the period 1968-71, ORVYL also benefitted from important contributions made by Richard Carr, Don Gold, and James Moore.
In order to achieve operating efficiencies, a redesigned ORVYL-II was introduced in 1973. Substantial cost reductions were achieved through basic changes to ORVYL'S paging and dispatching mechanisms implemented by Richard Carr. Parallel language and data base systems development also took place under the direction of Bob Berns (Languages Group), John Schroeder (SPIRES), and Donn Martin (BALLOTS).
ORVYL, is a new design intended to make maximum use of IBM hardware and OS/VS advances, was designed by the SCIP Interactive Systems Group and was the combined effort of Richard Carr, Carol Lennox, Richard Levitt, John Montague, Michael Powell, and William Skane, all under the direction of James Moore and Edgar Williams. It became a major part of the interactive system software developed by the Stanford Center for Information Processing, Charles R Dickens, Director.
Recent improvements to ORVYL have been made by Doug Fletcher, including a new hybrid file structure that permits very large files.
Much of ORVYL's flexibility comes from the Command Language Processor (CLP). In the timeshared environment, the ORVYL command language allows you to exercise a level of control over program execution and a "virtual computer" usually available only to an operator sitting at a computer console. By entering ORVYL commands at a terminal, you may direct the loading and execution of a program, as well as examine and modify an address space, with a small set of general purpose commands. Since both ORVYL and WYLBUR use the WYLBUR active file, a parallel command language structure has been developed between WYLBUR and ORVYL. For example, to store and retrieve the contents of a WYLBUR active file on a data set, you employ the SAVE and USE commands. Similarly, to pass data to and from an ORVYL file, you issue the PUT and GET commands.
ORVYL supports the interactive applications of the Stanford Public Information REtrieval System (SPIRES), and a number of interactive processors called public programs. ORVYL public programs currently implemented include SPITBOL, PL360, and a BNF Analyzer. APL, PL/C, BASIC, FORTRAN, WATFIV, Pascal, SCRIPT, and SORT are also available under ORVYL. For a list of programs currently supported, type the SHOW PROGRAMS PUBLIC command.
In the general form of an ORVYL command or macro instruction, lowercase letters identify the actual information to be entered. For example, the command form:
CREATE filename1 [FROM filename2 [APPEND]|[REPLACE]]
indicates that you must specify a valid file name(s) as part of the CREATE command.
- Square brackets, [ ], denote optional elements in an ORVYL command or macro instruction; they are not typed as part of the statement.
- Braces, { }, in the command form indicate that you must specify at least one of the
alternatives enclosed in the braces; braces are not typed as part of the statement.
- A vertical bar, |, separates alternatives or options.
Thus, in this example, you may use the CREATE command to copy the contents of filename2 to filename1 and optionally replace it (REPLACE), or add the contents of filename2 to the end of filename1 with APPEND.
An ORVYL file is a collection of data blocks. Each block is 2048 bytes or 4096 bytes in length depending upon the file system associated with the user's group code (GG). Users may write data blocks less than these lengths; however, since each block is stored in a fixed space, storage charges are equivalent for complete and incomplete blocks. The original length of the data in a block is stored in a block header, so when the user asks to read the block, the original data is returned. An ORVYL block may be created or released independent of any other block. No charges are assessed for blocks until they are created or written.
ORVYL maintains file names of the general form
ORV.gg.uuu.filename
gg identifies the accounting group in which the file was created.
uuu identifies the user who created the file.
filename is a file identifier containing as many as 33 alphanumeric characters. Legal alphameric characters for inclusion in a file name include the letters A -- Z, numbers 0 -- 9, asterisks (*), underscores (_), and periods (.). Segments in the complete file name are separated by periods. The first character of each segment must be a letter.
When creating or referencing an ORVYL file, the user who created the file need specify only the filename; group and user identification are supplied automatically by ORVYL. When access has been permitted by the file owner, other users may also reference one or more of the owner's files. The following chart lists the legal forms of address for ORVYL files, followed by a description of the type of user each form is intended to serve. All forms listed are legal for input to the Command Language Processor (CLP). However, only a subset may be used to name files in ORVYL macros.
Valid ORVYL Filename Forms | For | For | Description
| CLP?| Macro?|
---------------------------+-----+-------+------------------------------
ORV.gg.uuu.filename | Yes | Yes | Fully qualified filename
---------------------------+-----+-------+------------------------------
filename | Yes | Yes | Used by the file owner
---------------------------+-----+-------+------------------------------
@gg.&uuu.filename | Yes | Yes | For members of another group
&uuu.@gg.filename | Yes | Yes | with different user initials
---------------------------+-----+-------+------------------------------
&uuu.filename | Yes | Yes | For members of the file
filename USER uuu | Yes | No | owner's group
---------------------------+-----+-------+------------------------------
@gg.filename | Yes | Yes | For a member of a different
filename GROUP gg | Yes | No | group with the same user
| | | initials as the file owner
---------------------------+-----+-------+------------------------------
filename USER uuu GROUP gg | Yes | No | USER identifies the file owner.
filename GROUP gg USER uuu | Yes | No | GROUP identifies the owner's
| | | group.
---------------------------+-----+-------+------------------------------
filename ACCOUNT uuu$gg | Yes | No | ACCOUNT identifies the file
filename ACCOUNT gg.uuu | Yes | No | owner's initials and group.
---------------------------+-----+-------+------------------------------
filename PUBLIC | Yes | No | PUBLIC file (ACCOUNT GG.PUB)
---------------------------+-----+-------+------------------------------
When ORVYL file macros require specification of a user name (group identifier plus user initials), the forms gg.uuu or uuu$gg are both accepted. For use with the Command Language Processor (CLP), PUBLIC is accepted as a valid group and user identifier for the account in which the ORVYL public files reside (that is: GG.PUB).
Programs may create and write temporary ORVYL files during execution. (SEE the description of the ATTACH 2 macro in Section 5.) Such temporary files are erased as soon as the program detaches the file.
Throughout this manual, the term "filename" implies all of the valid ORVYL filename forms shown above. The term "account-info" implies any of the following:
USER uuu [GROUP gg] GROUP gg [USER uuu] ACCOUNT uuu$gg ACCOUNT gg.uuu PUBLIC
ORVYL files may be in a variety of formats. Record length (line length) and line numbers may vary. When creating ORVYL files, you can specify the format with the format options. They are:
[EDIT|CARD|PRINT|LRECL=nnn] [NUMBERED|INTEGER|UNNUMBERED]
The format options allow you to specify three attributes of the data set:
1. record format and length, using LRECL, etc. 2. WYLBUR line number format, using NUMBERED, etc.
They are meaningful in the commands GET and PUT. If you do not specify a format, ORVYL saves disk files in EDIT format (that is, EDIT is the default format). Once you have created a disk file with the desired format, ORVYL automatically recognizes the format for LINK, GET and PUT...REPLACE commands. Special caution must be used when specifying an explicit format for saving library members. The format attributes apply to the entire ORVYL user library and not the library members individually. Thus, if the format of the member does not agree with that of the library, ORVYL issues a warning message like the following:
Warning: Data set type will be changed to PO U/6356/6356 OK (Yes/No)?
If you reply OK, YES or Y, ORVYL changes the format of the library to the specified format. However, the new format attributes of the library may not reflect the actual format attributes of the older library members. Thus, programs using these members may encounter difficulties, and the SHRINK command may destroy the old members. ORVYL will be able to access the old members only if their format is explicitly given.
Option Descriptions
EDIT is the default for writing sequential data sets with the
PUT command. Internally, active files are always treated
as EDIT format. The line number format and position need
not be specified with the EDIT option. Library members
assume the format of the library as the default format.
CARD|PRINT|LRECL=nnn
specifies that the data set has fixed-length blocked
records (RECFM=FB) with a record length of nnn. nnn may
be an integer between 1 and 235 inclusive. On a PUT,
the records may be blocked up to a maximum of 6447
characters/block. If the blocking factor is not
specified on a PUT, ORVYL chooses an optimal blocking
factor based on device type. If the actual physical
block size is not an integral multiple of nnn on a read,
any characters remaining after all possible lines of nnn
characters have been extracted will become a separate
record. CARD is equivalent to LRECL=80. PRINT is
equivalent to LRECL=133. Using these options on a GET
command may produce some rather odd looking data if the
data set being read does not contain fixed records.
NUMBERED on a write operation (e.g., PUT), it specifies a
fixed-length blocked record format and that line numbers
are to be saved as part of the record in the normal ORVYL
line number form; that is, nnnnn.nnn with leading blanks
inserted as necessary and trailing zeroes suppressed. On
a read operation (e.g., GET, LINK), it specifies that the
data set is to be treated as NUMBERED fixed or variable
length blocked. For non-EDIT format data sets, ORVYL
uses the line number stored in the record and deletes
from the record the columns that contain the line number.
UNNUMBERED on a write operation (e.g., PUT), it specifies a
fixed-length blocked record format without line numbers
in the record. On a read operation (e.g., GET, LINK),
it specifies that the data set is to be treated as
UNNUMBERED fixed or variable-length blocked.
This is the default for CARD|PRINT|LRECL=nnn
INTEGER has the same meaning as NUMBERED except that the ORVYL
line number is multiplied by 1000, placed in an 8-digit
field, and padded with leading zeroes as necessary
(e.g., line number 1 becomes 00001000).
See the GET and PUT commands for additional options. [See 2.3.5, 2.3.6.]
ORVYL and WYLBUR both make use of the WYLBUR active file. The WYLBUR active file is an important interface between the ORVYL and OS/MVS file systems. It is a temporary or working collection of lines of text. Using the WYLBUR text-editing facility, lines may be inserted, replaced, or deleted on a line-by-line basis. Within lines, individual characters or character strings may be inserted, modified, or deleted. The WYLBUR active file provides a convenient means for introducing programs and associated data into ORVYL. Program output may be directed to the active file for listing at the terminal or on a printer. Output may also be written online to WYLBUR data sets or ORVYL files for later use. The ORVYL facilities controlling the storage of the contents of the WYLBUR active file in an ORVYL file and the transfer of the contents of an ORVYL file to your WYLBUR active file are the PUT and GET commands, respectively. [See 2.3.5, 2.3.6.]
An ORVYL file is created in one of the three following ways:
- with the PUT command, copying the contents of the WYLBUR active file to an ORVYL file.
- by a user program running under ORVYL. [See 3.4.]
- by execution of the LINK command, creating a file which contains an executable program. [See 3.1.]
The user may establish an ORVYL file with no contents using the CREATE command. An optional version of the CREATE command also permits the user to copy or append the contents of one file to another. File contents and directory information may be destroyed by execution of the ERASE command. Employing the RENAME command, the user may change the names of established ORVYL files.
CREATE filename1 [LIBRARY] [[FROM filename2 [APPEND]|[REPLACE]]
[format-options]|ALIAS membername] [QUIET]
The CREATE command writes a file directory entry in the ORVYL file system. The CREATE command with a filename and no other options creates a file with no contents in the ORVYL file directory.
The FROM filename2 option on the CREATE command puts a copy of the second file's contents into the new file being created.
The CREATE command can create library format files, library members, or sequential files.
Options:
filename1 the name for the ORVYL file being created. Type HELP
FILENAME for information on ORVYL file names.
LIBRARY creates an empty file in LIBRARY format.
FROM filename2 copies the contents of the ORVYL file named filename2 into
the new file being created with the name filename1. The
CREATE command does not copy file access permits from
filename1 to filename2.
REPLACE If REPLACE is specified with the FROM option, it replaces
the contents of filename1, if any, with the contents of
filename2. If the FROM option is not specified, it replaces
any existing contents in filename1 with an empty file.
APPEND copies the contents of filename2 to the end of filename1.
Block numbers for the new contents begin at the next
block after the last existing block number in filename1.
format-options describe the desired record length and how WYLBUR line
numbers should be treated. Type HELP FORMAT-OPTIONS
for a description of these options.
ALIAS creates a second directory entry for an existing ORVYL
library member, with the message "ALIAS for membername2" as
the title on the new library member created. The ALIAS option
only works in the form:
CREATE filename1#membername1 ALIAS membername2
QUIET suppresses the system response when the command is
successfully completed.
ERASE filename [CONTENTS] [LIBRARY] [QUIET]
The ERASE command removes the specified file from the ORVYL file system, destroying any file contents. Once you ERASE an ORVYL file, it is gone; however, files can be restored from backups maintained by the Systems Group.
Options:
CONTENTS deletes only the contents of the specified file, retaining
the ORVYL file directory information, file access
privileges, and file format information. You are charged
for the remaining index block.
LIBRARY erases a library format file, and all of its members.
Be sure you want to destroy the entire file before
using this option.
QUIET suppresses any message from the system if the command
is successfully completed. This is a standard option
on WYLBUR and ORVYL commands.
RENAME {filename1 TO filename2|library#member1 TO member2} [QUIET]
The RENAME command changes the name of an existing ORVYL file. It can also rename library members. The RENAME command does not affect the file contents or those statistics and access privileges maintained by ORVYL for the file contents.
Options:
filename1 TO filename2
filename1 is the current name of the ORVYL file to be
renamed.
filename2 is the new name for the existing ORVYL file. The
name must follow the rules for data set names. Type
HELP FILENAME for information on ORVYL file naming
conventions.
library#member1 TO member2
library#member1 is the current name of the library
member to be renamed. The name must be in the form
lib#member or lib(member).
member2 is the new member name for the existing ORVYL file.
It must be eight or fewer characters. Do not use the usual
library member notation (# or parentheses) when giving the
member name.
QUIET suppresses the system message when the command is
successfully completed. This is a standard option on
ORVYL and WYLBUR commands.
SHRINK filename [QUIET]
Deletes all empty blocks from the specified file. Does not modify file directory information or other file contents.
QUIET suppresses the system response when the command
executes successfully.
PUT filename [format-options] [(blocking factor)]
[HEX] [REPLACE|APPEND] [NUMBERED|INTEGER]
Copies the contents of the WYLBUR active file to the specified ORVYL file. Options:
Note: (1) This option is only valid for
use (a) with the CARD format when the
NUMBERED option is not employed or (b)
with the LRECL format specification. The
LRECL value n must be an even integer.
(2) Attempts to translate invalid hexa-
decimal characters to EBCDIC cause the
PUT command to be aborted.
In order to make use of the NUMBERED sequence and INTEGER sequence numbers in subsequent GET commands, the file must be retrieved GET NUMBERED or GET INTEGER. If neither option is specified, the contents of character positions 73-80 are treated like any other data.
GET filename [format-options] [HEX] [CLEAR|MERGE]
[SKIP=n] [LINES=n] [NUMBERED|INTEGER]
Copies the contents of the specified ORVYL file to the user's WYLBUR active file.
Options:
The ORVYL file system maintains a flexible security scheme for all user files. This system is based on the principle that access to each file must be explicitly stated and then controlled by the file owner. Access to a particular file or all files created by one user may be extended to any one or all other users.
When an ORVYL file is first created, no access is permitted to any user except the file owner himself. By specifying a level of access to a particular file or global access to all files with the SET PERMIT commands, the file owner may explicitly assign file control to other users.
SET PERMIT [filename] FOR {gg.uuu|GROUP gg|PUBLIC}
{{[READ][APPEND]|APPEND|WRITE|NONE} [EXTEND]}
The SET PERMIT command allows you to specify a number of different ways that other users may access your files. You may set access privileges for an individual file or for all files owned by you. However, you may not assign access privileges to individual library members; access permits apply to your entire library. You may restrict access to another specified user or group or may use the PUBLIC option to open your file(s) to all users. Access permits must be explicitly set. There are no default privileges assigned by ORVYL to an individual file or files; however, an ORVYL program, such as SPIRES, may establish defaults when it creates a file on your behalf.
To give another user access privileges to a single file: SET PERMIT filename FOR gg.uuu [access-level-option]
To give another user access privileges to all your files: SET PERMIT FOR gg.uuu [access-level-option]
To grant access privileges to another group to a single file: SET PERMIT filename FOR GROUP gg [access-level-option]
To give another group access privileges to all your files: SET PERMIT FOR GROUP gg [access-level-option]
To give all users access to your files:
SET PERMIT FOR PUBLIC [access-level-option]
Option Descriptions
filename the name of the file to which the SET PERMIT command is
applied. If you do not specify a filename, the command
will apply to all ORVYL files belonging to your account.
FOR account account is the user or users to whom you are assigning
privileges. This option may be in the form gg.uuu or
uuu$gg.
FOR GROUP gg gg is the group of users to whom you are assigning
privileges.
FOR PUBLIC PUBLIC assigns the specified privileges to the all
users.
READ permits reading of the file only. Does not allow any
changes to the file.
APPEND gives only the privilege of adding records to the end of
the specified file(s). By itself, APPEND does not include
the privilege of reading a file; to allow others to
both read a file and add records to it, you must
specify READ APPEND.
WRITE permits full access, including reading the file, making
changes to the file, appending records to the file, and
erasing the file.
NONE removes all previously assigned access privileges.
EXTEND permits the specified user to pass on to other users any
of the file access privileges granted to the specified
user. Only a file owner or a designated user may
extend previously assigned privileges. The file owner
always retains the ability to extend or deny privileges
to others.
The EXTEND privilege may not be given to PUBLIC.
SET SHARE filename
Prevents exclusive use of the specified file by any user. The file is to be used in common and may only be attached by user programs or the Command Language Processor with MODE=SHARE. Only the file owner may issue the SET SHARE command.
SET NOSHARE filename
Permits a user to attach the specified file to the exclusion of all others. Only the file owner may issue the SET NOSHARE command.
SET FILEMASK filename {WRITE|READ APPEND|APPEND|READ|NONE}
Limits all access to the specified file to the FILEMASK level, regardless of how other file access was obtained or to whom it was assigned. Only the file owner may issue the SET FILEMASK command.
SET CLP filename
Permits the execution of all ORVYL Command Language Processor commands otherwise available to the user for operation on the specified file. When a file is first created, SET CLP is in effect. Only the file owner may issue the SET CLP command.
SET NOCLP filename
Blocks the execution of the ORVYL file commands: ERASE, PUT, RENAME, SET PERMIT, SHOW FILES ERASE, and SHRINK. SET NOCLP does not affect processing of the specified file by a user program. SET NOCLP may only be issued by the file owner.
SET SPIFILE filename
The SET SPIFILE command blocks read access to an ORVYL file by any non-SPIRES ORVYL programs. A file with SPIFILE set may not be accessed by any program other than the public SPIRES programs or by any user other than the file owner. Access is not allowed either for batch SPIRES, batch FASTBILD, or test versions of SPIRES programs. The SHOW SPIFILE command displays the SPIFILE access for a designated ORVYL file. SET NOSPIFIL reverses the effect of the SET SPIFILE command.
SET NOSPIFIL filename
The SET NOSPIFIL command permits ORVYL files to be accessed by ORVYL programs other than SPIRES. It reverses the effect of the SET SPIFILE command. (Because ORVYL commands can only be 8 characters long, this command is spelled NOSPIFIL instead of NOSPIFIL.) The SHOW SPIFILE command displays the SPIFILE status of an ORVYL file.
The ORVYL file information commands allow the file owner, or any user with file access privileges, to display information on individual files. Available information includes the size of a specified file in ORVYL blocks (SHOW BLOCKS), the access privileges established for a specific file with the SET PERMIT command (SHOW PERMITS), the net level of access to a specific file for the issuing user (SHOW ACCESS), the file access privileges associated with all files created by a single user, and the SHARE status set for a particular file with the SET SHARE/NOSHARE commands.
DUMP can be used in place of SHOW to append results to Wylbur's Active File. For example:
DUMP FILES LIKE PPRISM ACC GG.SPI
SHOW BLOCKS [FILE] filename
Prints the number of ORVYL blocks included in the specified file, followed by the numbers of the first and last blocks in that file.
Note: If you have a filename of FILE or ACCOUNT or any abbreviation down to the first 3 letters, then you will have to either specify the fully qualified form of the filename or use the FILE option. Eg, SHOW BLOCKS FILE ACC
SHOW PERMITS filename [FOR access-group]
Lists the SET PERMIT access privileges currently in effect for the specified file.
FOR access-group restricts the list of users displayed:
access-group gg.uuu|uuu$gg The specific user or user's group. GROUP gg The specific group. PUBLIC The PUBLIC permission value.
SHOW ACCESS filename
Displays the access privileges available to the issuing user for the specified file. The privilege displayed is a combination of (1) the file and account-level permits for both the issuing user and PUBLIC and (2) the global access limit assigned by SET FILEMASK.
Note: If you have a filename that is ACCOUNT or any abbreviation down to ACC, then you will have to specify the fully qualified form of the filename to distinguish it from the ACCOUNT option.
SHOW SHARE filename
Displays the SHARE status set by the file owner for the specified file.
SHOW CLP filename
Displays the CLP condition set for the specified file by the file owner.
SHOW FILEMASK filename
Displays the access level assigned to the specified file with the SET FILEMASK command.
Available information on a user's files includes statistics on the number of allocated blocks and the number of blocks currently in use (SHOW BLOCKS) and an alphabetical listing of certain or all ORVYL files, selected according to optional criteria (SHOW FILES).
SHOW BLOCKS [ACCOUNT {uuu$gg|gg.uuu}]
Displays the current limit on the number of ORVYL blocks which can be allocated to the user, followed by the number of blocks currently in use.
Note: If you have a filename that is ACCOUNT or any abbreviation down to ACC, then you will have to specify the fully qualified form of the filename to distinguish it from the ACCOUNT option.
SHOW PERMITS [ACCOUNT {xxx$yy|yy.xxx}] [FOR access-group]
Prints a list of users who currently enjoy access to the specified user's files (ACCOUNT option). If no ACCOUNT option is specified, then ORVYL reports all access privileges assigned by the issuing user. Any user assigned access privileges may display all privileged users as well as the level of access assigned to each.
FOR access-group restricts the list of users displayed:
access-group gg.uuu|uuu$gg The specific user or user's group. GROUP gg The specific group. PUBLIC The PUBLIC permission value.
SHOW ACCESS ACCOUNT {uuu$gg|gg.uuu}
Displays the access privilege available to the issuing user for all files owned by the specified user (uuu$gg or gg.uuu). This privilege is a combination of the privileges assigned both the issuing user and PUBLIC.
Note: If you have a filename that is ACCOUNT or any abbreviation down to ACC, then you will have to specify the fully qualified form of the filename to distinguish it from the ACCOUNT option.
SHOW FILES [{LIKE|UNLIKE|FROM} name]
[account-info] [[BLOCKS] [DATED] [FORMAT]|[ALL]] [ERASE]
Lists in alphabetical order the names of all ORVYL files created by the user issuing SHOW FILES. Any of the following options may be appended to the SHOW FILES command to provide additional information or modify the file name display.
Options:
SHOW FILES ATTACHED
Displays the names of all those ORVYL files currently attached by the issuing user.
Under ORVYL, user programs may be executed by employing one of the ORVYL interactive language processors (e.g., PL/C, PL360, APL, BASIC, SPITBOL, etc.) or by loading standard OS object modules produced by OS/VS language processors. For instructions on the execution of programs written under the interactive language processors, the user should consult the detailed documentation available for each.
ORVYL accepts object modules produced on-line or from one of the following language processors: FORTRAN IV (G and H), PL360, OS Assembler, PL/1 and COBOL. Object modules are processed by the ORVYL loader to produce a load module. Load module output may then be executed directly or stored in an ORVYL load module library for subsequent execution.
SHOW VFILES [line-number] [LIKE filename] [ADDR] [RESERVED]
[COUNTS] [USER uuu] [FID n] [SHORT] [NODISP] [?]
The SHOW VFILES command provides information about ORVYL files (data sets) that are currently attached by users. The files are displayed by file system. Without any options, it produces a list of each currently attached file by every logged-on user, which can be quite long. It is especially useful when you want to find out if a particular file that you need exclusive access to is attached by anyone else, in which case you may want to use the LIKE option to limit the display to that particular file. This command is most often done as DUMP VFILES to append the result to Wylbur's Active File.
The format of the response is:
Line <nnnn> <gg.uuu> has file <ORV.gg.uuu.filename> <status> or.... Line <nnnn> <gg.uuu> is waiting for file <ORV.gg.uuu.filename>
where "<nnnn>" is the Milten line number of the logged-on user, "<gg.uuu>" is the user's account number, "<ORV.gg.uuu.filename>" is the name of the ORVYL file, and <status>" is either "(Shared)" or "(Exclusive)", depending on how the file is attached.
The following options can be used in any logical combination. Illogical combinations will give unpredictable results.
SHOW {CONTENTS|PROGRAMS} [FOR library] [account-info] [ALL] [ERASE]
The SHOW CONTENTS or SHOW PROGRAMS command displays an alphabetical list of member names for the specified library.
Option Descriptions
FOR library the name of the library whose members are to be displayed.
The default library is the user's library named PROGLIB.
account-info display the directory of a library belonging to an account
other than that of the logged-on user. One form of this
option is: ACCOUNT gg.uuu.
ALL displays the block allocation and usage for each member
of the library.
ERASE offers you the option of erasing members of the library.
After the name of the member has been displayed, ORVYL
prompts with "Erase?". A positive response (YES, Y
or OK) erases that member. Any other response is
interpreted as a negative response.
The LINK command invokes the ORVYL loader. Object modules may be input from a file in the ORVYL file system, from the user's WYLBUR active file, or from both. The LINK command is written in the general form
LINK {ACTIVE|FROM filename} [CLEAR] [LIST] [ENTER [PAUSE] [parm]]
where ACTIVE specifies that the contents of the user's WYLBUR active file are to be used as the primary input for LINK. The alternate form, FROM filename, directs LINK to the specified ORVYL file for input. ORVYL files for use as LINK input must be written in EDIT or CARD format. (SEE Section 2.3 for a description of ORVYL file formats.) CLEAR clears the previous contents of user memory, if any. LIST logs all LINK control statements and END's of object decks as they are processed.
ENTER instructs ORVYL to begin program execution immediately following the completion of LINK processing providing a NAME statement wasn't used to store the program in a LOADFILE. The PAUSE option for ENTER returns control to the Command Language Processor and sets the program entry point to the first instruction. Execution may then be initiated with the GO command. With the ENTER option, parameters may also be passed to the user program in any of the following forms:
---------------------------
| (text) or PARM=(text) |
---------------------------
| 'text' or PARM='text' |
---------------------------
| "text" or PARM="text" |
---------------------------
| PARM=token |
---------------------------
In the first three forms, text may be any set of characters, including matched sets of parentheses, doubled quotes, or doubled apostrophes. The token in the last form may not contain any special characters other than #, $, or @.
LINK input may consist of complete object modules, load modules, and the LINK control statements detailed below. The user should note that no WYLBUR, MILTEN, or ORVYL commands may be included in LINK input.
The following LINK control statements provide much of the flexibility available with the OS Linkage Editor. Certain OS Linkage Editor functions (e.g., OVERLAY) are not supported under ORVYL LINK. Other functions familiar to OS Linkage Editor users have been modified, while still others have been added specifically to fill the special requirements of the ORVYL programmer.
The OS Linkage Editor allows the programmer to specify certain error diagnostics, processing, and space allocation options in the OS JCL. Similarly, ORVYL provides a control statement PARM that specifies certain global options prior to the processing of all other LINK input.
PARM [option1] [option2] ...
must precede all other control statements in the LINK input. The following PARM options are currently available:
LINK control statements may not be placed within an object module. In several cases, the placement of control statements is restricted. The last paragraph of each section below indicates any restrictions. Control statements may be as many as 133 characters in length, but may not be continued from one line to the next. Blanks are used to separate operands in LINK control statements.
If a file contains an INCLUDE or other control statement that specifies a second filename, then the default USER and GROUP for the second file is taken from the first.
ALIAS specifies additional names for the output library member. As many as 16 aliases may be specified for one library member.
ALIAS symbol [symbol ...]
where symbol is defined as a control section, entry name, or alternate name for the program. When the program is executed by calling an ALIAS which is a control section or entry name, execution begins at the external name referenced.
An ALIAS statement must precede the NAME statement used to specify the member name.
CHANGE replaces an external symbol by the new symbol enclosed in parentheses following the external symbol.
CHANGE external-symbol (new-symbol) ...
where external-symbol may be a control section name, an entry name, or an external reference. New-symbol is the name to which the external symbol is to be changed.
A CHANGE statement must immediately precede either (1) the object module containing the external symbol to be changed or (2) the INCLUDE statement which specifies that object module.
COMMENT documents LINK processing. ORVYL logs all COMMENT messages at the user terminal as they are encountered in LINK input.
COMMENT any-text
ENTRY specifies the symbolic name of the first instruction to be executed when the program is ENTERed or called by its module NAME.
ENTRY external-name
where external-name is the name of an instruction, not a data name.
An ENTRY statement must precede the NAME statement for the module, if one exists.
EXPAND lengthens a control section or named common section by a specified number of bytes.
EXPAND name (xxxx)
where name is the symbolic name of a common section or control section, the length of which is to be increased, and (xxxx) is the decimal number of bytes to be added to the length of the common section.
An EXPAND statement must immediately follow the object module which contains the control or common section to which it refers. If the module contains more than one section, then the named section must be the last one defined.
INCLUDE specifies ORVYL files or LOADFILES that are to be sources of additional input for LINK. INCLUDE statements are processed in the order in which they appear in the input. Only one file or LOADFILE may be processed per INCLUDE statement.
INCLUDE filename [(membername...)]
where filename is the name of a file or LOADFILE to be used as an additional source of input. For a LOADFILE, at least one membername must be specified. Other files must be written in EDIT or CARD format.
NAME specifies the name of the program to be stored in a LOADFILE. Serves as a delimiter, allowing multiple program processing in a single pass.
NAME membername [(R)]
where membername is the name to be assigned to the program created from the preceding input. (R) indicates that this program replaces an identically named module in the output LOADFILE. After a NAME statement has been processed, memory is automatically cleared for the next program. Once stored in a LOADFILE, the CALL command may be used to execute the stored program.
The NAME statement is placed after the last object module or control statement that is to be used for the program.
PAGE aligns a control section or named common area on a 4K page boundary.
PAGE [{common-area-name|csectname} ...]
where common-area-name is the name of the common area to be aligned on a page boundary. Csectname is the name of the control section to be aligned on a page boundary. If no name is specified, then the next common or control section encountered in the input is aligned on a page boundary.
The PAGE statement must immediately precede either (1) the object module which defines the common area or control section or (2) the INCLUDE statement which specifies that object module.
REPLACE specifies one or more of the following:
- Replacement of one control section with another.
- Deletion of a control section.
- Deletion of an entry name.
REPLACE {csectname1 [(csectname2)]|entry-name} ...
where csectname is the name of a control section. If csectname1 is used, the control section is deleted; if csectname2 is also specified, the first control section is replaced with the second. Entry-name is the entry name to be deleted.
The REPLACE statement must immediately precede either (1) the module containing the control section or entry name to be replaced or deleted or (2) the INCLUDE statement which specifies the module.
LOADFILE specifies the LOADFILE in which the program is to be placed by a NAME statement following LINK processing. If this statement is not included in the LINK input, PROGLIB is the default LOADFILE.
LOADFILE filename
where filename is the name of the LOADFILE member.
Note: If a number of programs are linked at the same time, the last named LOADFILE is assumed for each program.
The LOADFILE statement may be placed anywhere before the NAME statement.
SYSLIB specifies an automatic call library for LINK processing. As many as eight libraries may be specified in separate SYSLIB statements.
SYSLIB filename
where filename is the name of a LOADFILE.
The SYSLIB statement must precede the NAME statement for each program that is to make use of the automatic call libraries.
ZAPNAME identifies a CSECT in a load module that is to be modified by subsequent ZAPVER and ZAPREP control statements.
ZAPNAME [csectname]
where csectname is the name of a previously defined control section.
ZAPVER compares the contents of the control section defined by the ZAPNAME statement at a specified location with text supplied by the user.
ZAPVER [hex-offset] [text]
where hex-offset is the hexadecimal displacement of the data to be inspected and text is supplied by the user for comparison with the data. The value of hex-offset must be between 0 and the length of the CSECT. Text may be a sequence of hexadecimal digits or a character string enclosed by quotation marks. Text data may not be separated by commas.
A ZAPVER statement must be preceded by a ZAPNAME statement.
ZAPREP modifies data at a specified location in the control section previously defined by the ZAPNAME statement. User-supplied data replaces the currently defined contents.
ZAPREP [hex-offset] [text]
where hex-offset is the hexadecimal displacement of the data to be modified and text is supplied by the user for replacement. The value of hex-offset must be between 0 and the length of the CSECT. Text may be a sequence of hexadecimal digits or a character string enclosed by quotation marks. Text data may not be separated by commas.
A ZAPREP statement must be preceded by a ZAPNAME statement.
LINK output is stored in a load module library called a LOADFILE. A LOADFILE may contain any number of programs. Normally, only the Command Language Processor will be used to read and write LOADFILES.
Whenever a NAME statement is encountered in LINK input, a corresponding load module is stored in the user's LOADFILE. If the LINK input also contains a LOADFILE control statement (SEE Section 3.2), then the LOADFILE name is derived from that statement. If no output name was specified during LINK, ORVYL assigns output to PROGLIB, the default LOADFILE assigned each user. PROGLIB is created automatically when the user first creates a load module.
A LOADFILE maintains a directory that contains member and alias names. This directory is automatically extended as the need arises, subject only to the user's total ORVYL file space allocation. LOADFILE member and alias names, along with PARM controls specified during LINK, may be displayed with the SHOW PROGRAMS command.
SHOW PROGRAMS [LIBRARY loadfile] [account-info]
where SHOW PROGRAMS displays member names, alias names, and corresponding PARM controls for the issuing user's PROGLIB. The option LIBRARY directs ORVYL to the specified loadfile for the display. The account-info options (see 2.2) identify a PROGLIB or LOADFILE created by another user. For example, SHOW PROGRAMS PUBLIC displays all the available ORVYL public programs in the public PROGLIB (ACCOUNT PUB$gg).
Programs contained in a LOADFILE or an entire LOADFILE may be deleted using the ERASE command:
ERASE loadfile [#program|(program)]
When a member is deleted, all aliases for the member are also erased. Space formerly occupied by the member is returned to the file system.
If a "private" program is stored in a LOADFILE, any attempt to read or write the LOADFILE is precluded. (SEE the PRIV LINK control statement in Section 3.2.) User programs may not ATTACH a LOADFILE that contains a private program.
The CALL command allows direct execution for programs stored in a LOADFILE (created by LINK processing). For ease in debugging, a PAUSE option permits the user to load the program only. The GO command may then be employed to initiate execution. The EXIT command clears the loaded program from user memory.
CALL name [LIBRARY loadfile] [account-info]
[CLEAR] [NOSHARE] [PAUSE] [parm]
CALL initiates execution of the specified program. If the name is an external entry point as well as an alias, execution begins at the entry point.
Options:
---------------------------
| (text) or PARM=(text) |
---------------------------
| 'text' or PARM='text' |
---------------------------
| "text" or PARM="text" |
---------------------------
| PARM=token |
---------------------------
In the first three forms, text may be any set of characters, including matched sets of parentheses, doubled quotes, or doubled apostrophes. The token in the last form may not contain any special characters other than #, $, or @.
SET ENTRY external-symbol
SET ENTRY sets the entry point of the program to the specified symbol. SET ENTRY must be specified before the program is first entered.
The SHOW ENTRY command displays the current program entry point.
GO
Used to begin execution after calling a program with the PAUSE option. See Chapter 4 for debugging commands you can issue before executing, including additional options on the GO command.
ENTER [PAUSE] [parm]
ENTER initiates execution of a program previously loaded with the LINK command. At ENTER, external symbols are resolved from libraries.
Options:
---------------------------
| (text) or PARM=(text) |
---------------------------
| 'text' or PARM='text' |
---------------------------
| "text" or PARM="text" |
---------------------------
| PARM=token |
---------------------------
In the first three forms, text may be any set of characters, including matched sets of parentheses, doubled quotes, or doubled apostrophes. The token in the last form may not contain any special characters other than #, $, or @.
SHOW CORE
SHOW CORE displays a summary of the user's memory utilization.
SHOW MAP [CSECT] [EXTRN] [ENTRY] [COMMON] [DUMMY] [FROM symbol]
Displays all external symbols in alphabetical order, where options display the following information:
CSECT - control section name
EXTRN - unresolved external references
ENTRY - resolved entry points
COMMON - common section names
DUMMY - external dummy section names
FROM symbol - begin the MAP display at the
specified symbol
EXIT
EXIT clears the user's program and detaches all input/output devices.
SET REGION [nnnnK]
ORVYL provides each user with a region of memory in which the program executes. The exact size of the memory allocated to each user is variable and can be changed with the SET REGION command. The default region is the maximum allowed.
nnnnK specifies the size of the region in kilobytes. This is the
size of the user's work space, which may not be as high as the
total available region space if a program is already loaded.
SHOW REGION
This command shows the size of the Program and Work areas. The following is an example:
Program region: 11204K Program area: 964K Work area: 10240K
Once execution has begun, the user can exert control over the program in several important ways. Command-driven programs allow the user to EXIT the problem program unconditionally. In addition, the program may also contain a facility that passes control to the Command Language Processor using the PAUSE macro. If, for example, the program is designed so that unrecognized commands are passed directly to the Command Language Processor, the PAUSE command can be employed to halt program execution and give control to CLP.
Using the ATTN or BREAK terminal key is a more direct means of control for problem programs. When a terminal is in output or idle mode, an ATTN is a request for a processing break. Control is passed to the user program's ATTN exit routine, if one exists. Otherwise, a session break is scheduled and control is passed to CLP. When the user program's ATTN exit routine is entered, the program should cease processing and request further instructions in the form of reading a command from the terminal. If the program does not issue a terminal read, a second ATTN passes control directly to CLP. Users should pause prior to the second ATTN to allow the program sufficient time to respond.
If the terminal is in input mode, an ATTN does not cause a session break. A user program may choose to ignore an ATTN on input and reprompt for input. For this case, a meta-ATTN, a single question mark followed by an ATTN, has been defined. On input, a single question mark followed by an ATTN always forces a session break.
To resume execution following a session break, the user may issue the GO or ATTN command. GO resumes execution at the point at which the program interrupt occurred. ATTN resumes execution at the user's attention exit routine, if one exists, and simulates an immediate ATTN upon program resumption.
SET TIMER m.n
The SET TIMER commands interrupts an ORVYL program at the specified time interval and displays the total program CPU time usage up to that point. "m" is seconds and "n" is tenths of a second. This command helps you keep track of how much CPU time an ORVYL program uses. To turn the timer off, use the command SET TIMER 0. The SHOW TIMER command displays the time set on the ORVYL timer.
There are several commands available that provide general information about the ORVYL environment. These commands may be used at any time.
SHOW VUSERS [[session-id]|[SPO origin-address]]
The SHOW VUSERS command displays information about session activity for each user in ORVYL. The SHOW VUSERS commands returns: the session-id (Milten line number), account name, program name, I/O count and CPU time for each current ORVYL session. If you specify a Session ID, SHOW VUSERS returns this information for that session only.
To get the list of ORVYL users in your active file, type the command DUMP VUSERS.
SHOW VINFO
The SHOW VINFO command displays general information about ORVYL. The following is an example:
ORVYL:
Started at 05:21:06 11/04/01 (01.308)
Number of CPUs = 3
Current real memory = 507M (192M min, 512M max)
User memory origin = 5M
0 CLP errors
Total Orvyl run time = 1 04:56:10.78
Total CPU time = 0 07:06:04.71
Charged CPU time = 0 05:46:26.40
Dispatch CPU time = 0 00:15:21.64
I/O service CPU time = 0 00:03:22.93
File system I/O summary: Bitmap: 31969 cache reads, 23590 disk reads, 27974 disk writes Catalog: 201844 cache reads, 15588 disk reads, 823658 disk writes IXR: 78421467 cache reads, 114420 disk reads, 1396408 disk writes User: 31498626 cache reads, 10419340 disk reads, 3103556 disk writes
Individual files attached: 2152 high-water: 2167
Total user files attached: 88679 high-water: 88764
Total temp files attached: 1722 high-water: 1724
Total temp blocks in use: 8411 high-water: 8415
Designated file system for temporary files: ITS4K
File system cache summary:
2K System cache: 13000 cache buffers
78252012 lookups (78119068 in cache, 100%), 2324675 updates
2K User cache: 34000 cache buffers
41825907 lookups (31370569 in cache, 75%), 13385383 updates
4K System cache: 1000 cache buffers
536374 lookups (536212 in cache, 100%), 76743 updates
4K User cache: 4000 cache buffers
138748 lookups (128057 in cache, 92%), 184200 updates
(The SHOW VBLOCKS command gives additional info.)
SHOW VBLOCKS
The SHOW VBLOCKS command displays general information about the ORVYL file systems. The following is an example:
GENERAL: 333436 blocks available 7929175 total 2K 987810 IOs 86.5% reduced NSI: 408864 blocks available 7294841 total 2K 3909124 IOs 86.1% reduced SOCRATES: 130880 blocks available 6026173 total 2K 15988 IOs 76.6% reduced ITS: 456874 blocks available 11735179 total 2K 2446787 IOs 93.9% reduced FIS: 2303086 blocks available 14906849 total 2K 6151809 IOs 85.8% reduced SNAP: 6 blocks available 4557189 total 2K 1554288 IOs 36.9% reduced OOD: 562389 blocks available 3171670 total 2K 9643 IOs 52.0% reduced SDCACCT: 190748 blocks available 350553 total 2K 82 IOs INFACCES: 207187 blocks available 311808 total 2K 247 IOs ROUTE66: 317357 blocks available 2854503 total 2K 654794 IOs 81.5% reduced ITS4K: 160003 blocks available 200316 total 4K 261337 IOs 71.7% reduced
SHOW VGROUP group-code
The SHOW VGROUP command displays the ORVYL file system information associated with the given two-character group-code. The following is an example:
SHOW VGROUP GQ
File System ID: 3 Name: ITS
SHOW VSYS
The SHOW VSYS command displays a table of all shared programs. The following is an example:
Name Users Size Origin SPB Program DISPLAY 9 12K 00059000 01400000 ORV.GG.PUB.PROGLIB(DISPLAY) OVAM 0 16K 000DC000 01400080 ORV.GG.PUB.VAMLIB(OVAM) PRINTER 0 20K 00000000 01400100 ORV.GG.PUB.PROGLIB(PRINTER) PSPIRES 9 1024K 81602000 01400180 ORV.GQ.PRD.PRIVLIB(SPIRES) SPIRES 1633 1024K 81402000 01400280 ORV.GG.SPI.PROGLIB(SPIRES) SPIBILD 0 512K 0005C000 01400300 ORV.GG.SPI.PROGLIB(SPIBILD) PEMSDATA 0 112K 8180A000 01400480 ORV.GQ.EMS.PEMS.PROGLIB(PEMSDATA) EMSDATA 0 20K 81702000 01400E80 ORV.GQ.EMS.EMS.PROGLIB(EMSDATA)
If the Origin is non-zero, then the program is currently loaded. If the Origin begins with 8, it is a 31-bit mode program, and may be loaded above the 16-meg line (above x'00FFFFFF').
SHOW VSYM
The SHOW VSYM command displays a table of all shared symbols. The following is an example:
Program Users Value Symbol
PEMSDATA 152 0180AB08 S7PEMS
0181F148 S3<0010>GQ.EMS.EMSPROTOS<0005>PROTO<000B>PEMS.ACTIVE
0181BBB0 S3<0010>GQ.EMS.EMSPROTOS<0005>PROTO<000A>PEMS.RMAUX
01819960 S3<0010>GQ.EMS.EMSPROTOS<0005>PROTO<0007>PEMS.SM
018178B0 S3<0010>GQ.EMS.EMSPROTOS<0005>PROTO<0007>PEMS.RM
018171F8 S3<0010>GQ.EMS.EMSPROTOS<0005>PROTO<0004>PEMS
01821228 S2GQ.EMS.PEMS.VERSION
018212F0 S2GQ.EMS.PEMS.MSGVARS
01820E38 S2GQ.EMS.PEMS.ADRVARS
01820CA0 S2GQ.EMS.SETUP.VARS
01816C90 S1<0006>GQ.EMS<0002>**<000B>PEMS.EXPAND
01816890 S1<0006>GQ.EMS<0002>**<000C>PEMS.RESOLVE
01811F00 S1<0006>GQ.EMS<0002>**<000D>PEMS.READAUX2
0180E388 S1<0006>GQ.EMS<0002>**<000D>PEMS.READAUX1
0180B108 S1<0006>GQ.EMS<0002>**<000C>PEMS.READMSG
EMSDATA 153 0170436A S6EMS DISTRIBUTION
0170430A S6EMS NAME INDEX
01703858 S5ORV.GQ.EMS.DIRECTORY.<02>
017037A8 S5ORV.GQ.EMS.DIRECTORY.<0B>
01702B08 S5ORV.GQ.EMS.DIRECTORY.<01>
01703FA8 S4ORV.GQ.EMS.DIRECTORY.<FF>
A Session Break occurs when a user program is interrupted during execution. In a Session Break, control is returned to the ORVYL Command Language Processor. A Session Break may be initiated by the user at his terminal, by the user program, or by a user program error. During a Session Break, any ORVYL command may be used to display or modify program status. The user program may prevent modification of the WYLBUR active file during a Session Break. The following table describes the Session Break types.
Session Cause
Break
ATTENTION (1) Typing an ATTN while the user
terminal is printing or is idling.
(2) Typing only a question mark (?)
followed by ATTN while the terminal
is awaiting input.
PAUSE Execution of a PAUSE macro by
the user program.
PANIC Detection of a PANIC condition
by the system or the user program.
TRAP Execution of a user-specified program
trap.
PROGRAM Detection of a user-specified program
EVENT event.
MONITOR Execution of a selected MONITOR CALL
instruction.
The user may resume program execution from a session break by issuing the GO or ATTN command. The GO command returns control to the user's program, resuming execution at the point at which the interrupt occurred. The ATTN command returns control to the user's program, but simulates an interrupt before the next instruction.
GO [TO location] [EVENTS n] [NOLIST] [CONTINUE] [TRAP location]
The GO command begins program execution or resumes it following a session break. If a TO location is not specified, execution continues at the point where the program interrupt occurred.
Options:
ATTN [EVENTS n] [NOLIST] [TRAP location]
The ATTN command resumes program execution following a session break, starting execution at the program's exit routine, if one exists. In effect, it simulates an immediate ATTN upon program resumption.
Options:
ORVYL provides a number of program diagnostic commands for use during a Session Break. Employing these commands, the user may display
- The contents of a core location.
- A summary of the user's memory utilization.
- The contents of the program registers.
- The contents of floating-point registers.
- The current program status word.
- The contents of registers saved at the last interrupt.
- The program status word saved at the last interrupt.
- Established program traps.
- The value of an expression.
In each of the following commands, the SHOW form causes the specified information to be displayed at the terminal. You can substitute DUMP for SHOW to cause the specified information to be appended to the user's WYLBUR active file.
SHOW CORE [start-address-expression
{length|TO end-address-expression}
[MATCH {hexadecimal-expression|'string'}
{length|TO end-address-expression} [REPEAT]]]
Displays the contents of the specified core location. If no location is specified, prints a summary of the user's program area utilization. [See 4.4.] for a definition of expression. The MATCH option instructs ORVYL to search for a hexadecimal expression or string over the range from the starting address to an ending address. The REPEAT option causes it to go to the next occurrence of the match value.
SHOW ADDRESS expression
Displays the value of the specified expression in decimal and hexadecimal representation. [See 4.4.] for a definition of expression.
SHOW GPR [first-register [last-register]]
Displays the contents of the specified general register or range of general registers. If no registers are specified, ORVYL reports the contents of all registers (0-15).
SHOW FPR [first-register [last-register]]
Displays the contents of the specified floating-point register or range of floating-point registers. If no registers are specified, ORVYL reports the contents of all floating-point registers.
SHOW PSW [FORMAT]
Displays the user program status word. The FORMAT option displays the various fields within the PSW.
SHOW SAVEGPR [first-register [last-register]]
Displays the contents of the range of general registers saved at the last interrupt. If no registers are specified, ORVYL reports the contents of all interrupt general registers (0-15).
SHOW SAVEPSW [FORMAT]
Displays the program status word saved at the last interrupt or most recently modified by a PATCH SAVEPSW command. The FORMAT option displays the various fields within the PSW.
SHOW ALL [NOCORE] [NOMAP]
Displays the user program status word (PSW), the contents of all general and floating-point registers, SAVEGPRS, SAVEPSW, information on memory utilization, and the program map. The option NOCORE suppresses memory utilization information; NOMAP suppresses the program map.
The ORVYL debugging commands below permit the user to modify program status during a Session Break. A general expression, as employed below, may be replaced by any one of the following quantities:
- An external name in the program MAP. The value substituted for the external name is the address associated with that name.
- A decimal integer. Decimal integers may be whole numbers only; that is, they begin with a non-zero digit and contain no decimal points.
- A hexadecimal integer. A valid hexadecimal integer consists of the numbers 0-9 and the letters A-F, and begins with a zero digit (0).
The arithmetic operators +, -, *, and / may be employed in general expressions. As in FORTRAN, the arithmetic operators * and / take precedence. Parentheses may also be used to control the order of evaluation in a general expression.
ORVYL supports seven expression notations with special meanings:
NOTATION MEANING
* Substitute the current user program PSW
instruction address for *.
@n Substitute the lower 24-bits of the
current contents of the general program
register n for @n in the expression, where
n is a decimal integer from 0 to 15.
nK Substitute the value of n multiplied by
1024.
nM Substitute the value of n multiplied by
the hexadecimal value X'100000'.
>n Substitute the word at location n in the
user's virtual memory, where n is a pointer
to the desired value.
$hhh Substitute the value of the start of the
program address space plus the quantity
hhh for $hhh in the expression, where hhh
is a hexadecimal integer. In this case, hhh
need not begin with a zero (0).
#hhh Substitute the value of the start of the
user work space plus the quantity hhh
for #hhh in the expression, where hhh is a
hexadecimal integer. In this case, hhh need
not begin with a zero (0).
Note: A register-expression must be evaluated as a valid program register. A location-expression is any expression which evaluates to a valid program address. A hexadecimal-expression must consist of only hexadecimal digits, and need not begin with a zero (0).
PATCH CORE location-expression
{hexadecimal-expression|'character-string'}
[VERIFY {hexadecimal-expression|'character-string'}|NOVERIFY]
Changes the value at the specified core location. The VERIFY option causes ORVYL to abort the patch if the string does not match the current contents of the location. If neither VERIFY nor NOVERIFY is specified, ORVYL indicates the previous value of the patched location. The NOVERIFY option causes this message to be suppressed.
PATCH GPR register-expression expression
Changes the value of the specified general register.
PATCH FPR register-expression hexadecimal-expression
Changes the value of the specified floating-point register. The value patches from left to right within the register.
PATCH IA expression
Changes the user instruction address.
PATCH PSW byte-displacement hexadecimal-expression
Modifies the specified bytes of the user program status word. See Section 5 for a definition of the user program status word.
PATCH SAVEGPR register-expression expression
Alters user interrupt register to the value of the specified expression.
PATCH SAVEIA expression
Alters user interrupt instruction address to the value of the specified expression.
PATCH SAVEPSW byte-displacement hexadecimal-expression
Alters the specified bytes of the user interrupt program status word to the value of the specified hexadecimal expression.
The user may cause a Session Break at a predetermined point in program execution by setting a program trap. A Session Break occurs after execution of the instruction located at the trap address.
When the user sets a program trap, ORVYL assigns the trap an index number. This index is displayed at the terminal and must be used to later reference the trap.
NOTE: ORVYL does not permit program traps to be set on an SVC instruction, on any location other than on a halfword boundary, or on a location already specified as a trap.
SET TRAP location-expression
Establishes a program trap at the specified location. ORVYL indicates the trap index number assigned.
SHOW TRAPS
Displays the index number and location(s) of all program traps currently enabled as well as the first halfword of the instruction trapped at each location.
CLEAR TRAP index-number
Clears the program trap defined at the specified index position.
CLEAR TRAPS
Clears all defined program traps.
ORVYL supports program event recording (PER) and monitoring, two tools helpful in program debugging. Program event recording detects (1) successful execution of a branch instruction, (2) changes in the contents of specified general registers, (3) an instruction fetch from specified main-storage location(s), and (4) changes in the contents of specified main-storage location(s). Program monitoring permits detection of selected MONITOR CALL instructions as they are encountered in the user program.
Program event recording may be invoked by specifying a PER control block in the program or by issuing the SET EVENT command at the terminal. Monitoring is initiated by setting a program monitor mask or with the SET MONITOR command.
The user program controls those conditions that are considered events for recording purposes; it can specify one or more events to be detected. When a specified event does occur, control passes to the user's PANIC exit routine. Information identifying the event type is passed to the exit routine in register 15.
Control information for program-event recording is contained in a 12-byte control block provided by the user program.
CONTROL BYTES CONTROL INFORMATION
WORD
0 0-3 Event masks (bits 0-3)
General register masks (bits 16-31)
1 4-7 Starting address (bits 8-31)
2 8-11 Ending address (bits 8-31)
PER Event Masks -- Bits 0-3:
Bit: 0 Successful Branching Event 1 Instruction Fetching Event 2 Storage Alteration Event 3 General Register Alteration Event
When a bit is one (1), the corresponding event is monitored; when a bit is zero, the event is not monitored.
PER General Register Masks -- Bits 16-31:
Specify which general registers are monitored for content alteration. These 16 bits correspond one-to-one to the 16 general registers in ascending order. When a bit is one (1), the register is monitored for alteration; when zero, the register is not monitored.
PER Starting Address -- Bits 8-31:
Contains the beginning address for the main storage area to be monitored.
PER Ending Address -- Bits 8-31:
Contains the ending address for the main storage area to be monitored.
Program event recording may be enabled by specifying (1) a PANIC exit routine and (2) a PER control block with a non-zero event mask. The PANIC exit routine and PER control block are specified by the SET 7 and SET 17 supervisor operations, respectively.
When PER is enabled and a specified program event takes place, an interrupt occurs and the PANIC exit routine is entered. The PER code and PER address are written in register 15. Bits 0-3 contain the PER code (event type); bits 8-31 contain the PER address of the instruction which caused the event.
Programming Note: Program event recording is controlled by the PANIC bit in the PSW mask byte. When the PANIC bit is zero, a program event does not cause an interrupt. The user should note that the PANIC bit is set to zero whenever a user exit is entered.
The SET EVENT command causes a session break whenever specified program events occur in the user program. All program events to be recorded must be specified with a single SET EVENT command.
SET EVENT [[FETCH] [STORE] [RANGE=(first-address[ last-address])]]
[BRANCH] [REGISTER={(list)|ALL}]
SET EVENT cancels the effect of any previous SET EVENT command. A SET EVENT command is aborted if the user program has already established a program event control block. The CLEAR EVENT command disables program event recording. The SHOW EVENT command displays the SET EVENT command currently in effect, if any.
When the user program has set a PANIC exit routine (SET 7) and a non-zero monitor mask (SET 18), MONITOR CALL instructions pass control to the PANIC exit routine and place monitor information in register 0.
The monitor mask is contained in a 4-byte control block provided by the user program. Bits 16-31 of the monitor control block correspond one-to-one to monitor classes 0-15. Any number of monitor mask bits may be on at any one time.
The contents of bits 8-15 of the MONITOR CALL instruction constitute the monitor class number. The address specified by the B1 and D1 fields of the instruction forms the monitor code.
When a MONITOR CALL instruction is processed and the corresponding monitor mask is one, a monitor interrupt occurs. At the interrupt, the monitor code number (bits 0-7) and the monitor code (bits 8-31) are returned in register 0.
The SET MONITOR command may be used to selectively cause a session break upon execution of a MONITOR CALL instruction.
SET MONITOR {list|ALL}
list Enables monitoring for each class (0-15)
specified in the list.
ALL Enables monitoring for all MONITOR CALL instructions.
SET MONITOR cancels any previous SET MONITOR command. The SET MONITOR command is aborted if the user program already employs the MONITOR exit feature. The CLEAR MONITOR command disables program monitoring. Any MONITOR CALL instruction executes as a NOP following a CLEAR MONITOR command. The SHOW MONITOR command displays the SET MONITOR command setting currently in effect, if any.
Programming Note: Program monitoring is controlled by the PANIC bit in the PSW mask byte. When the PANIC bit is zero, a MONITOR CALL instruction executes as a NOP and does not cause an interrupt. The user should note that the PANIC bit is set to zero whenever a user exit is entered.
Technical information on program event recording and monitoring are available in the OS/390 Principles of Operation, IBM Publication SA22-7201.
ORVYL offers the programmer a broad range of supervisor services at the assembly language level. ORVYL macro instructions allow the programmer to exercise control over system activities and facilities in each of the following areas:
- Terminal input and output
- WYLBUR input and output
- ORVYL file input and output
- ORVYL file access privileges
- User program management
When assembled, each macro instruction expands into one or more executable machine instructions. The generated instructions load the program-specified parameters into the appropriate registers and issue a supervisor call instruction (SVC). Returns from the SVC instruction are then loaded in the appropriate registers by the supervisor; all registers not altered by the SVC remain unchanged. In general, error conditions are indicated by the value returned in register 15.
The catalogued macro library SYS3.ORVYL.UMACLIB includes the prototypes for all macros described in Section 5. To assemble ORVYL programs, the user may either employ the standard catalogued procedure ASMORVYL or write the appropriate JCL for calling the assembler with the above macro library.
The catalogued procedure ASMORVYL is a copy of the standard ASMC procedure in which those DD cards that reference standard VS macro libraries are replaced by one DD card that references the ORVYL macro library. When assembling ORVYL programs for use under the ORVYL File Batch Access Method (VAM/390), the BATCH macro must always be invoked before calling any other ORVYL macros. The BATCH macro initializes the assembly for expansion of all succeeding ORVYL macros to be processed under VAM. See Section 6 for a description of the File Batch Access Method (VAM/390).
NOTE: ORVYL employs registers 0, 1, 14, and 15 to pass macro parameters. Unlike OS/VS2, a supervisor save area in register 13 need not be provided under ORVYL.
Input and output to an ORVYL device occurs under the following general I/O protocol, where a device is defined as a file, terminal, or other device enabled for use under WYLBUR/MILTEN/ORVYL. To make use of an ORVYL device, that device must first be attached by the program (SEE ATTACH macro). Each request for input or output (READ, WRITE, etc.) is normally followed by the WAIT instruction. A WAIT must always be issued prior to another request which employs the same device. (SEE WAIT macro). WAIT coordinates competing demands for input and output service and provides the user program with concurrent computing and input/output capabilities. When processing is complete, the programmer detaches the device, relinquishing control to other potential users.
Most every user program request for input/output occurs in the following sequence. The user program
- issues the SVC to perform the input/output operation;
- checks the return code to detect whether or not the operation has begun;
- if operation has not begun, performs error processing;
- if operation has begun, issues a WAIT SVC for the input/output operation;
- checks the return code from WAIT to detect whether or not the operation has successfully completed;
- if operation is not successful, performs exception processing;
- if operation is successful, continues with next program task.
In general, a return of zero from the input/output SVC and the WAIT SVC indicates that the operation has begun or that the operation is successful, respectively.
ORVYL provides two terminal communication protocols, one providing line-by-line input and output, the other servicing display terminals. Display input and output services allow the ORVYL programmer to converse with display terminal devices connected to ORVYL through MILTEN with a PDP-11 front-end system. Two terminal modes are available when using display terminals, 2741 MODE and DISPLAY MODE. 2741 MODE recognizes the device for line-by-line input and output. DISPLAY MODE I/O allows full screen input and output, providing the ability to format the screen using multiple prompts. Existing ORVYL programs can operate with display devices in 2741 MODE with no program changes.
The ORVYL macro CONTROL 21 allows the ORVYL program to sense the terminal type and characteristics. Conditions set by macros CONTROL 2 (SET TABS), CONTROL 8 (embedded control character in column 1), and CONTROL 26 (NEWLINE) are ignored when MODE=DISPLAY.
DISPLAY MODE I/O allows three additional READ options, all of which are totally dependent upon those features available on the particular display device being used. The SUPPRESS option removes trailing blanks from READ data fields and adds a field terminator character. The SCREEN option returns the entire contents of the display face as READ data when the user types SEND ENTER or RETURN. The IMMEDIATE option returns data in the mode specified without any intervention by the user.
When the user program prepares a buffer containing data for transmission to the display terminal, the EBCDIC character codes presented in the table below should be placed in the buffer to control positioning on the screen. These symbolic definitions are provided in the ORVYL macro DSPCODES. Legal abbreviations for the following EQU values is shown in parenthesis preceeding the description.
Control Character Definitions for MODE=DISPLAY
OUTPUT CODES
CURSRET EQU X'0D' (CR) Back up cursor to start of line
ERASLINE EQU X'3C' (EL) Erase line, cursor to end
LINEFEED EQU X'25' (LF) Move cursor down one line
CURSDOWN EQU X'25' (CD) Same as LINEFEED
NEWLINE EQU X'15' (NL) ERASLINE - CURSRET - LINEFEED
CURSUP EQU X'1B' (CU) Move cursor up one line
CURSFOR EQU X'2B' (CF) Non-destruct cursor space
CURSBACK EQU X'16' (CB) Non-destruct cursor backspace
BACKSPAC EQU X'16' (BS) Same as CURSBACK
CURSHOME EQU X'12' (HC) "Home" cursor (line 0, co. 0)
TAB EQU X'05' (HT) Jump to next input field
BACKTAB EQU X'3B' (RT) Backup to previous input field
ERASCREN EQU X'1C' (ES) Clear screen and CURSHOME
ERASDATA EQU X'1D' (EU) Clear unprotected fields only
STARTUNP EQU X'1F' (SU) Write following data unprotected
STARTPRO EQU X'19' (SP) Write following data protected
BELL EQU X'2F' (BEL) Ring console alarm
IDLE EQU X'17' (IL) Null timing character
CURSADDR EQU X'11' (AC) Jump cursor (followed by 2 data
bytes - line no., col. no.)
INPUT CODES
FIELDSEP EQU X'22' (FS) End-of-field for SUPPRESS option
The ORVYL macros which allow a user program to communicate with WYLBUR can be grouped into three categories: (1) those macros which allow the user program to read or write the WYLBUR active file employing terminal I/O services, (2) those macros which allow the user program to pass commands to WYLBUR, ORVYL, and MILTEN, and (3) those macros which allow the user program to employ WYLBUR text-editing facilities.
A user program can read or write the contents of the WYLBUR active file by designating a MODE=TEXT option for the terminal READ and WRITE macros. These forms are called READ TEXT and WRITE TEXT macros. To read the active file, the program specifies an input area which will receive active file data, the format in which WYLBUR is to pass the data, and a line number or associative range which specifies the data to be passed. The available formats are analogous to those format options which a user may specify in a WYLBUR USE or LIST command.
To write data to the active file, the program issues a WRITE macro with the TEXT option. This macro specifies an output area which contains the data, a format indicator which instructs WYLBUR on how to interpret the data, and an operation specification which indicates whether the data is to be used to delete, replace, or insert lines in the active file.
In addition, ORVYL CONTROL macros are available for the following purposes:
- Report the number of lines in the active file.
- Obtain the line number of the first line in the active file.
- Detect the line number of the last line in the active file.
- Delete the contents of the active file.
- Instruct WYLBUR to type a given line of the active file to the terminal.
- Sense the user's option settings in WYLBUR.
- Set and report the WYLBUR mode word.
The WYLBUR mode word is a collection of flags which affect processing of macro calls and controls issued by the user program. The PREST/UNPREST flag indicates whether data is to be passed in a compressed or uncompressed form. For READ TEXT and WRITE TEXT macros, the PREST/UNPREST flag is the only mode word flag that affects input and output.
A user program can utilize MILTEN, WYLBUR, and ORVYL command processing as an extension of program command processing by using one of the following macros:
- COMMAND
- WRITE EDIT (Terminal WRITE macro with MODE=EDIT option)
- MILCOM
- READ EDIT (Terminal READ macro with MODE=EDIT option)
These four macros, in conjunction with the terminal READ TEXT and WRITE TEXT options, eliminate the need for developing editing capabilities or duplicating code in each user program. These macros add the entire command language capability of all interactive systems to the user program. The user who does not wish to utilize extended program command processing must process all terminal input/output within the program.
In considering which of the above macro calls, if any, are to be employed, the programmer should consider the control he wishes to exert over command prompting at the terminal and over interactive systems command processing. In general, to control all command prompting and processing by an interactive system (e.g., all WYLBUR or all ORVYL commands), the programmer employs the COMMAND, WRITE EDIT or MILCOM macro calls to selectively pass those commands not recognized by the user program to the desired interactive system. To specifically assign WYLBUR the task of command prompting and processing, the programmer employs the READ EDIT macro call. Under READ EDIT, WYLBUR processes those commands that it recognizes and passes unrecognized commands to the user program.
Using the COMMAND macro, a program specifies the area containing a command string and indicates that the command string is to be passed until recognized either by all systems (WYLBUR, MILTEN, and ORVYL) or by some combination of systems.
Alternatively, the program may issue a WRITE EDIT macro, specifying the the area which contains a command string. The command string is then passed only to WYLBUR and MILTEN for processing. To limit command processing to MILTEN only, the program issues the MILCOM macro.
Both of the above macros can be employed by a program for (1) the processing of program generated commands or (2) the processing of unrecognizable commands received in response to a normal terminal READ command issued by the program. Both macros give the program the ability to utilize the full power of MILTEN, WYLBUR, and ORVYL command processing to augment program functions.
Issuing the READ EDIT macro causes control of the terminal to be relinquished to WYLBUR for both command prompting and command processing. Control returns to the user program whenever the user enters a command at the terminal that is not recognized by WYLBUR. The program may then process the command if it is able to, issue the COMMAND macro which instructs ORVYL and MILTEN to attempt processing, write an error message to the terminal, or any combination of the above.
When using the READ EDIT and WRITE EDIT macros, WYLBUR mode word flags define what types of changes to the active file are to be allowed.
The following flags may be set:
WYLBUR issues an error message at the terminal whenever it receives a command blocked by a mode word flag. Under WRITE EDIT, control is immediately returned to the user program following an error message. For READ EDIT, WYLBUR prompts again and retains control.
In addition, an INFORM flag may be set to indicate that the user program must be informed of all changes as they take place. When this flag is set, WYLBUR returns changes to the user program on a line-by-line basis unless the command causing the changes is a USE, FETCH or COPY command. In those cases, WYLBUR will return as many lines as will fit into that input area specified by the user program in the READ EDIT macro call. Since most WYLBUR commands can change more than one line in the active file, the program must continue to issue successive READ EDIT macros in order to process all changes.
If the user does not wish program command prompting to be resumed automatically by WYLBUR once all changes associated with a single command have been reported, the CHANGES option can be included with the EDIT option on each READ EDIT call. The CHANGES option causes WYLBUR to report changes as described above; however, once all changes for a particular command have been reported, WYLBUR returns control of the terminal to the user program instead of retaining control of the terminal and issuing a new command prompt.
When using READ EDIT with the WYLBUR mode word set to cause reporting of changes, two additional macros are available to control the processing sequence between the user program and WYLBUR. These are (1) an "abort" macro to stop any pending, unreported changes in a READ EDIT sequence and (2) a "grant permission" macro to quarantee that the user program only processes information which has been reported.
Under ORVYL, a user's virtual memory is managed in an address space divided into pages. An ORVYL page consists of 4096 bytes of memory. Each page begins at an address which is a multiple of 4096. (In hexadecimal representation, decimal 4096 is 01000; thus, any address which ends in three zeros is a multiple of 4096.)
The ORVYL supervisor sets an upper limit on the total number of pages which can be made available to each user program at any one time. Within this general constraint, ORVYL permits the user program to reserve that number of pages actually required to complete the program task, as well as to release pages whenever they no longer are needed for the program.
The user begins each session with a null and undefined ORVYL memory. A null memory condition means that no ORVYL pages have yet been reserved for the user's program. Such a null memory condition also occurs whenever an EXIT SVC is processed or the EXIT command is typed at the terminal.
In order to make use of ORVYL memory, a sufficient number of pages must first be explicitly or implicitly reserved. Any attempt by an ORVYL program to make use of memory addresses on pages which have not been reserved results in a program error.
When the user instructs ORVYL to load a program for execution (see the discussion on program loading in Section 3), the ORVYL loader automatically reserves a sufficient number of pages to accomodate the program. This address space then remains reserved until the program terminates execution.
During execution, the user program may request additional memory for the program work area. Using the SET 14 supervisor operation, the program specifies the amount of memory required. When this request can be satisfied, ORVYL reserves the necessary number of pages and returns the initial address to the executing program.
The executing program may make any number of memory requests subject only to ORVYL's overall limit on the number of pages available to each program. An optional form of the SET 14 macro allows the program to request that the largest possible program work space be reserved.
Programs may release all or part of previously reserved memory with the SET 15 macro. Any attempt by an ORVYL program to release pages which were not reserved results in a program error. The ability to release does not extend to memory reserved by the ORVYL loader.
Since the SET 15 macro releases memory in page units, the release request should always specify a page boundary as the starting address and a memory length that is a multiple of the page size (4096). Release requests which overlap a fractional part of a page cause the entire page to be released.
Once an ORVYL page has been reserved, the contents of that page must next be defined. ORVYL considers a page to be defined as soon as the user program stores information in it. Whenever the contents of a particular page are no longer required, the user program should act to free the contents of that page. Designed for this purpose, the SET 1 supervisor operation frees the contents of a page without releasing it from the program's addressable memory. Timely use of this feature reduces paging activity, the total use of auxiliary memory, and virtual memory charges.
The SET 2 macro advises the paging supervisor of those pages which have become inactive but ought to remain defined. This macro helps the paging supervisor find those pages which may be best removed to auxiliary memory for a period while other pages are brought into real memory.
The SET 0 macro permits the user program to define more than one page in a single operation. Used mainly by the ORVYL loader, this feature ensures that uninitialized large arrays and common areas are always defined at the point of program entry.
The following table summarizes the types of exit routines which ORVYL allows the programmer to establish, with a description of that event which causes exit routine entry.
EXIT ROUTINE REASON FOR ENTRY
TIMER Time interval expired.
SVC An SVC instruction numbered
0-195 was issued.
PANIC The system or the user program
detected a PANIC condition, a
program event, or a monitor call
instruction.
ATTN The user typed an ATTN at the
terminal during output (CPU
control), or typed a question
mark (?) followed by an ATTN
during input (terminal control).
WAIT An operation on the device was
completed. Issuing a WAIT
macro will now cause no delay
in execution.
(0) Monitor information if a MONITOR CALL
interrupt occurs. SEE Section 4.6 for
information on MONITOR CALL interrupts.
(1) SVC - SVC number
PANIC - PANIC code
ATTN - Device identifier
WAIT - Device identifier
(14) Information supplied when the user's exit
routine was established. SEE the description
of SET (5-9).
(15) Program event information if a PROGRAM
EVENT interrupt occurs. SEE Section 4.6
for information on PROGRAM EVENT interrupts.
SVC SVC number
PANIC <=0 Complement of user PANIC code
>0 Program Interrupt Code
Bit 24: 1 PROGRAM EVENT interrupt
Bit 25: 1 MONITOR CALL interrupt
Bits 26-31: 1 Operation exception
2 Privileged operation exception
3 Execution exception
4 Protection violation
5 Addressing exception
6 Specification exception
7 Data exception
8 Fixed overflow
9 Fixed divide exception
10 Decimal overflow
11 Decimal divide exception
12 Exponent overflow
13 Exponent underflow
14 Significance Exception
15 Floating Divide Exception
16 Two I/O operations issued
for same device or file
with no intervening WAIT
A MONITOR CALL interrupt or program exception may occur simultaneously with a PROGRAM EVENT interrupt. If a PROGRAM EVENT occurs, PER information is returned in register 15; if a MONITOR CALL occurs, monitor information is returned in register 0.
When a program interruption occurs, the program status word (PSW) and registers are saved in the supervisor save area. The exit routine may sense the save area using an ORVYL macro. The mask byte is set to zero upon exit routine entry.
BYTE(S) CONTENTS
¬ 0-1 Interruption code
¬
¬ 2 Bits 0-1 Instruction length code
¬ 2-3 Condition code
ORVYL ¬ 4-7 Program mask
¬
PSW ¬ 3 mask byte Bit 0 1=Timer exit enabled
¬ 1 1=ATTN exit enabled
¬ 2 1=WAIT exits enabled
¬ 3 1=PANIC exit enabled
¬
¬ 4-7 Instruction address
8-71 General registers 0-15
When the exit routine has performed all the tasks assigned to it, the exit routine transfers control using an ORVYL macro. ORVYL will use the original save area to resume program execution unless the program specifies use of a modified copy of the original save area.
Each of the macro instructions below is described in the following format:
- Macro instruction general form
- Purpose
- Operands
- Returns
In the general form, the macro name appears in uppercase letters and may be coded directly. Operands are presented in lowercase letters and are described individually in the operands section. Operands enclosed in square brackets are optional elements in the macro instruction. The brackets are not coded in the macro instruction. Macro parameters are positional. When an option is omitted for a particular instruction, a comma must be coded in its place. The applicable register for each operand is listed in parentheses directly below the operand. In general, the registers used by ORVYL macros (i.e., registers 0, 1, 15, 14) are loaded in the order in which parameters are specified. Return values for affected registers from both the macro expansion and WAIT are listed in the returns sections.
An operand presented in the form xxx-la indicates that the address may be coded in either explicit or implied form. The macro will expand to execute a load address (LA) instruction and load the parameter register indicated in parentheses with the address. If an address already exists in a register, the operand may be written as an absolute expression enclosed in parentheses. The macro will expand to execute a load register (LR) instruction to load the parameter register from the register specified by the expression. If the address is already in the parameter register, the expression should consist of the register number expressed as a decimal integer.
An operand written in the form xxx-l or xxx-lh operates the same as la , but a load (L) or load half-word (LH) instruction is generated in place of the LA instruction.
The user may specify the instruction used to load a parameter register by prefixing the operand by LA:,L:,LH:,or IC: or by enclosing a register operand in parentheses. The table below shows the code generated by the macro expansion for each form of specification.
PARAMETER GENERATED CODE
(expression) LR p,expression
LA:expression LA p,expression
L:expression L p,expression
LH:expression LH p,expression
IC:expression SR p,p
IC p,expression
Whenever MODE is specified as part of a macro call, one or more operands may be complemented by the macro expansion. In order to avoid error, specified operands must be non-negative. Unless the operand registers are specifically modified by the supervisor routines, ORVYL returns complemented registers to their uncomplemented state before passing control to the user program.
ATTACH (0),(1),(15),(14) LCR 0,0 MODE=WAIT LCR 1,1 MODE=SHARE,CONTROL LCR 15,15 MODE=OLD SVC 249 ATTACH VAM CODE=00 COMMAND (0),(1),(15) LCR 1,1 MODE=WYLBUR LCR 15,15 MODE=NOCLP SVC 254 COMMAND VAM CODE=04 CONTROL (0),(1),(15),(14) LCR 0,0 MODE=WAIT LCR 1,1 MODE=FORMAT SVC 245 CONTROL VAM CODE=08 DETACH (0) SVC 248 DETACH VAM CODE=12 EXIT SVC 253 EXIT VAM CODE=16 MILCOM (0),(1),(15),(14) SVC 238 MILCOM VAM CODE=60 PANIC (0) SVC 252 PANIC VAM CODE=20 PAUSE SVC 255 PAUSE VAM CODE=24 READ (0),(1),(15),(14) LCR 0,0 MODE=WAIT LCR 1,1 MODE=TEXT,CHANGES,TRUNCATE LCR 15,15 MODE=EDIT,CHANGES,SKIP LCR 14,14 MODE=DISPLAY SVC 247 READ VAM CODE=28 RELEASE (0) SVC 243 RELEASE VAM CODE=32 RESERVE (0) LCR 0,0 MODE=WAIT SVC 244 RESERVE VAM CODE=36 SENSE (0),(1),(15),(14) SVC 250 SENSE VAM CODE=40 SET (0),(1),(15),(14) SVC 251 SET VAM CODE=44 STATUS (0),(1),(15),(14) SVC 241 STATUS VAM CODE=48 WAIT (0) SVC 242 WAIT VAM CODE=52 WRITE (0),(1),(15),(14) LCR 0,0 MODE=WAIT LCR 1,1 MODE=TEXT,DISPLAY LCR 15,15 MODE=EDIT,DISPLAY SVC 246 WRITE VAM CODE=56
Makes a device available for use by a program. See ATTACH under each device type for further information.
DETACH id-l
(0)
Specifies that an attached device is no longer required by the program and that this device will not be used again until another ATTACH macro is issued.
id-l device identifier
(15) = 0 Operation started.
No registers changed.
WAIT id-l
(0)
Suspends program execution until the current operation on the specified device is completed. Every operation must be followed by WAIT before another request to that device can be initiated.
id-l device identifier
SEE the values returned for specific operations.
ATTACH 1[,MODE=WAIT]
(0)
Attaches the terminal which began the session.
(15) = 0 Operation started. (0) = 32-bit terminal identifier
(15) = 0 ATTACH completed.
WAIT is optional when attaching the terminal.
READ id-l,location-la,length-la[,prompt-la]
(0) (1) (15) (14)
Reads a line of input from the terminal. A prompt may be specified, as well as a message to precede the prompt. A maximum response time from the terminal may also be specified (TIME-OUT feature). Specifying a TIME-OUT on READ does not affect operation of any other timer set by the program (i.e., those enabled by the SET 3 and SET 4 macros).
id-l terminal identifier
location-la location of input area
length-la
1st 16-bits: number of seconds to wait before
TIME-OUT (600 maximum) or zero
2nd 16-bits: length of input area (data may be
lost if less than 133 bytes)-zero illegal
prompt-la location of the area containing a prompt and/or
message text
If a prompt and/or message text is specified, the area must contain an output line and a prompt in the following format:
Field size: Contents:
2 bytes w(Length of message text to be written) - may be zero
2 bytes p(Length of prompt) - may be zero
w bytes Line to be written
p bytes Prompt Total of not more than 163
characters
Note: If message text is specified, ORVYL appends a Carriage Return to the line.
(15) = 0 Operation begun.
(15) = 0 Successful completion.
4 Input line terminated with ATTN. (Input buffer
contains all characters typed before ATTN.)
8 Read terminated by TIME-OUT.
-4 Permanent I/O error.
-8 Illegal tab used.
(1) = Number of bytes read.
WRITE id-l,location-la,length-la
(0) (1) (15)
Writes a line of output to the terminal.
id-l terminal identifier
location-la location of the area containing the line
length-la length of the area in the legal range zero (0)
through 163
(15) = 0 Operation begun.
(15) = 0 Successful completion.
-4 Permanent I/O error.
4 ATTN typed during terminal output.
Note: Unless CONTROL 25 has been set, ORVYL appends a Carriage Return to lines transmitted to the terminal.
READ id-l,location-la,length-la,outbuf-la,MODE=DISPLAY
(0) (1) (15) (14)
Reads either a set of responses to prompts or the contents of the scope face at the completion of the READ. With the exception of the immediate option, a maximum response time may be specified (TIME-OUT feature). A set of fields is contained in "outbuf", each of which describes a write count, a prompt count, a read count, write text and prompt text. These fields are used to create a display on the scope face and to define unprotected and protected spaces on the scope face. Protected spaces are defined by write and prompt data, while those unprotected spaces into which the terminal user may type his responses are defined by the read counts.
id-l terminal identifier
location-la location of input area.
length-la
1st 16 bits: Number of seconds before TIME-OUT
(600 maximum) or zero
2nd 16 bits: Length of input area - zero illegal
(data may be lost if less than 133
bytes), maximum is 4096
outbuf-la Two bytes of option codes which specify how and
when data is to be returned. If no option code is
specified, responses are padded with trailing blanks
to the specified length of the read field.
The meaning of on-bits is as follows:
Bit: Meaning:
16 IMMED Read immediate (no intervention by
user required).
15 SCREEN Read entire screen (write, prompt, and
read data when user enters SEND or
equivalent).
14 SUPPRESS Read responses only and suppress
trailing blanks (end of field marked
by field separator character).
13-1 Reserved.
After the option code, two bytes of length of
the output buffer which follows must be speci-
fied. If no output data exists the length field
should be zero.
The output data, if there is any, must follow
the count. The output buffer consists entirely
of data fields, which are defined as follows:
Subfield size: Contents:
2 bytes w (Length of write data) -
may be zero
2 bytes p (Length of prompt data) -
may be zero
2 bytes r (Length of unprotected
read area)
w bytes Write data
p bytes Prompt data
An unprotected area on the scope is defined each
time a non-zero "r" subfield is encountered.
Screen formatting controls are contained in the
write and read prompt data.
(15) = 0 Operation begun.
(15) = 0 Successful completion.
-4 Permanent I/O error.
-8 Illegal tab used.
-12 Illegal terminal for MODE=DISPLAY.
4 Input screen terminated with ATTN.
8 Read terminated by TIME-OUT.
(1) = Number of bytes read.
Input Area = For no options:
The area contains each response padded with
trailing blanks up to the length of the
specified read field.
For SUPPRESS option:
The area contains each response delimited by the
field separator character.
For SCREEN and IMMEDIATE options:
The area contains the full contents of the scope
face.
For READ MODE=DISPLAY, a sufficiently large return area must be specified in order to return the requested data. If no options are specified, the sum of the "r" lengths is sufficient. For the suppress trailing blank option, the number of "r" length fields must be added to the sum of the "r" lengths to ensure a sufficient return area. In any case, if the return area is too small, data will be discarded.
WRITE id-l,location-la,length-la,MODE=DISPLAY
(0) (1) (15)
Writes data to the scope face. No options apply in this mode.
id-l terminal identifier
location-la location of the area containing write data
length-la length of the area (zero illegal)
Display control characters may be interspersed with write data. The member 'CODES' in SYS3.ORVYL.UMACLIB may be used to obtain definitions for a number of commonly used control characters. See section 5.2.1 for a list of these codes.
(15) = 0 Operation begun.
(15) = 0 Successful completion.
-4 Permanent I/O error.
-12 Illegal terminal for MODE=DISPLAY.
4 ATTN typed during output.
NOTE:
No Carriage Return is appended to the output buffer when transmitted to the display terminal. The program includes screen formatting instructions in the output buffer.
Core storage in ORVYL is divided into pages of 4096 bytes each. A buffer area must begin on a double-word boundary and may not cross more than one page boundary. If a page boundary is crossed the buffer must extend at least 8 bytes on the second page. Thus, a buffer of 4096 bytes or less may begin on any double-word. A buffer of 6144 bytes may begin as much as 2048 bytes from the beginning of a page, while an 8192-byte buffer must begin on a page boundary. For maximum efficiency buffers of 4096 bytes or less should reside on a single page.
CONTROL id-l,code-la,n-la
(0) (1) (15)
Controls page eject and spacing on the terminal with no other data transmission. Ignored when MODE=DISPLAY.
id-l terminal identifier
code-la operation code
Code: Meaning:
0 Space n blank lines, where 0 < n < 66 (Any
value greater that 66 is treated as a page
eject.)
1 Page eject (Skip 4 lines.)
n-la Number of lines to space for CONTROL 0
(15) = 0 Operation begun.
(15) = 0 Successful completion.
-4 Permanent I/O Error.
4 ATTN typed during output.
CONTROL id-l,code-la,location-la
(0) (1) (15)
Sets tabs on the terminal.
id-l terminal identifier
code-la operation code
Code: Operation:
2 Set tabs.
3 Sense tabs.
location-la Location of the 16-byte area which contains or
will receive the tabs. Each byte specifies a tab
position and is a positive integer less than or
equal to 133. The first zero byte encountered
terminates tab setting. Each succeeding tab
position must be greater than the preceeding tab
position.
(15) = 0 Operation begun.
(15) = 0 Successful completion.
CONTROL id-l,code-la
(0) (1)
Controls translation of all terminal input. Affects both direct input to an ORVYL program and input to WYLBUR.
id-l terminal identifier
code-la operation code
Code: Operation:
4 Translates all lowercase alphabetic
characters to uppercase (SET UPPER).
5 Cancels translation of lowercase alphabetic
characters (SET UPLOW).
6 Senses translation status.
(15) = 0 Operation begun.
(15) = 0 Successful completion (codes 4 and 5).
0 Upper translation in effect (code 6).
4 Uplow translation in effect (code 6).
CONTROL id-l,code-la
(0) (1)
Controls page eject and spacing on the terminal based on the first character of each output line transmitted to the terminal after the CONTROL macro is issued. CONTROL (7-9) ignored when MODE=DISPLAY.
id-l terminal identifier
code-la operation code
Code: Meaning:
7 No control characters to be contained in
output lines.
8 First character in each line is a con-
trol character. Control characters are
interpreted and not printed. Legal con-
trol characters include:
blank Skip no lines before
printing.
0 Skip one line before
printing.
- Skip two lines before
printing.
1 Page eject before printing.
(Skip 4 lines.)
Any other character found in column 1 is
interpreted as a blank.
9 Sense whether control character inter-
pretation is being performed.
(15) = 0 Operation begun.
(15) = 0 Successful completion (codes 7 and 8).
0 No control character interpretation is being
performed (Code 9).
4 Control character interpretation is being
performed on the first character of each output
line.
CONTROL id-l,21,location-la
(0) (1) (15)
Provides current information about the user terminal and the current session.
id-l terminal identifier
location-la Location of the 60-byte area which is to receive
the terminal information. The format of this
area may be obtained by invoking the TTYP macro
in the ORVYL user's macro library. The data
returned includes:
· Hardware information: MILTEN line number,
port address, line speed, carriage width,
screen depth, etc.
· User established information: account,
name, tabs, privileges, and settings (e.g.,
CASE/BACK/TERSE/COMM/FASTLIST/TIMEOUT).
(15) = 0 Operation begun.
(15) = 0 Successful completion.
NOTE: The TTYP macro may be used without parameters to establish labels for referencing returned data. If no parameters are specified, all labels are prefixed with the mnemonic TTYP. If another prefix is desired, the user can code 'PFX=string', where 'string' is a 1 to 4 character label in the operand field. This string is used as the label prefix.
CONTROL id-l,code-la
(0) (1)
Forces the occurrence of a Session Break if the user types ATTN to terminate output or to interrupt computing. Facilitates the debugging of programs that have ATTENTION exits.
id-l terminal identifier
code-la operation code
Code: Operation:
22 Inhibits a Session Break following ATTN
(default condition).
23 Forces a Session Break following ATTN.
24 Senses the Session Break condition.
(15) = 0 Operation begun.
(15) = 0 Successful completion (codes 22 and 23).
0 Session break forced (code 24).
4 Session break inhibited (code 24).
CONTROL id-l,code-la
(0) (1)
Controls the automatic carriage return (NEWLINE) supplied at the conclusion of a normal terminal WRITE. CONTROL 25 suppresses the automatic carriage return; CONTROL 26 reenables automatic carriage returns. In addition, the NEWLINE status set by CONTROL 25 or reset with CONTROL 26 may be sensed with CONTROL 27.
id-l terminal identifier
code-la operation code
Code: Operation:
25 Suppresses an automatic NEWLINE at the
end of WRITE operation.
26 Reenables the automatic NEWLINE.
27 Senses the NEWLINE condition.
(15) = 0 Operation begun.
(15) = 0 Operation successful (codes 25 and 26).
0 NEWLINE supplied at end of terminal WRITE
operation (code 27).
4 NEWLINE not supplied (code 27).
Notes:
When the automatic NEWLINE function is suppressed, successive WRITE operations cause all output to be printed on a single line. A NEWLINE character (X'15') must be included in the data stream in order to initiate a new physical line.
A WRITE with NEWLINE suppressed followed by a READ operation unlocks the terminal following the last character of the WRITE text.
CONTROL id-l,28
(0) (1)
Obtain DELTA from Wylbur.
id-l terminal identifier
(15) = 0 Operation begun.
(15) = 0 Successful completion (1) = Current DELTA setting in Wylbur.
Note: DELTA is returned as an integer with 1 representing 0.001
The term 'WYLBUR PREST format' refers to that type of WYLBUR internal text storage which compresses text strings by removing multiple blanks. The use of this format generally reduces the space required to store character data. The ORVYL programmer has the option of receiving or sending active file data in this format when requests are made to WYLBUR.
Associated with each prest line is a length count. Since prest lines have all blanks removed, a line composed of only blank characters is defined by a length count of zero (0).
Lines that contain at least one non-blank character also contain "blank/non-blank" count bytes. A "blank/non-blank" count byte is divided into two half-bytes; the first half-byte is the "blank" count and the second half-byte is the "non-blank" count. Each non-blank character string in the line is preceded by a "blank/non-blank" count, indicating how many blanks preceded the non-blank (first half-byte), and the length of the non-blank string (second half-byte). The non-blank character string follows this "blank/non-blank" count byte. This pattern is repeated until the length count associated with a given prest line is exhausted.
The length count at the beginning of each prest line is the sum of the number of "blank/non-blank" count bytes plus the number of non-blank characters contained in the line. If a blank string in the unprest line exceeds 15 characters in length, successive "blank/non-blank" count bytes occur. If a non-blank string exceeds 15 characters in length, count bytes are inserted between each sub-string of 15 non-blank characters.
CONTROL id-l,12,word-la
(0) (1) (15)
Sets the WYLBUR mode word, directing WYLBUR in its processing of READ TEXT, WRITE TEXT, READ EDIT and WRITE EDIT calls. This setting remains in effect for all subsequent WYLBUR requests or until another CONTROL 12 is issued.
id-l terminal identifier
word-la WYLBUR mode word.
ON bits: Meaning:
31 PREST Returns line from the active
file in WYLBUR PREST
format. Affects READ EDIT,
WRITE EDIT, READ TEXT, and
WRITE TEXT requests.
30 INFORM Informs program of changes to
the active file on READ EDIT
and WRITE EDIT requests.
29 BLOCK Blocks execution of all
commands which cause changes
to the active file on READ
EDIT and WRITE EDIT requests.
28 NONUM Blocks execution of the NUMBER
command on READ EDIT and WRITE
EDIT requests.
27 NOALGN Blocks execution of the ALIGN
JUSTIFY and CENTER commands
on READ EDIT and WRITE EDIT
requests.
26 SBBLOCK Ensures that BLOCK, NONUM,
and NOALGN are in effect
during all Session Breaks.
25 SYNTAX Indicates that commands with
syntax errors should still
be passed to program.
8-24 Reserved for future use.
0-7 A character to prefix WYLBUR command
prompts in READ EDIT mode. A zero (0)
indicates that no prompt prefix is
to be used.
NOTE: When an ORVYL program is first
entered, the command language
processor sets the prompt
prefix to '-'. CONTROL 12
allows the user to change or
eliminate the prefix.
(15) = 0 Operation begun.
(15) = 0 Successful completion.
CONTROL id-l,13
(0) (1)
Returns the current setting of the WYLBUR mode word.
id-l terminal identifier
(15) = 0 Operation begun.
(15) = 0 Successful completion. (1) = Current WYLBUR mode word setting.
CONTROL id-l,14
(0) (1)
Reports the current size of the WYLBUR active file.
id-l terminal identifier
(15) = 0 Operation begun.
(15) = 0 Successful completion. (1) = Number of lines in WYLBUR active file.
CONTROL id-l,15
(0) (1)
Reports the line number of the first line in the active file.
id-l terminal identifier.
(15) = 0 Operation begun.
(15) = 0 Successful completion.
4 Active file is empty.
(1) = Line number of the first active file line (times 1000).
CONTROL id-l,16
(0) (1)
Reports the line number of the last line in the active file.
id-l terminal identifier
(15) = 0 Operation begun.
(15) = 0 Successful completion.
4 Active file is empty.
(1) Line number of the last active file line (times 1000).
CONTROL id-l,17
(0) (1)
Deletes the current WYLBUR active file contents.
id-l terminal identifier
(15) = 0 Operation begun.
(15) = 0 Successful completion.
CONTROL id-l,18
(0) (1)
Aborts any READ EDIT or WRITE EDIT command processing which is in progress in WYLBUR. A CONTROL 18 issued under other processing control is ignored.
id-l terminal identifier
(15) = 0 Operation begun.
(15) = 0 Successful completion.
NOTE:
A CONTROL 18 abort request is issued by the supervisor whenever a Session Break occurs for any reason. Since the program cannot control when these events occur, a CONTROL 20 permission request should be issued each time a changed line in a READ EDIT input area is about to be processed.
When a CONTROL 18 is issued, all command processing and changes reporting is aborted. If the user program is processing a multiple line buffer containing changes (READ EDIT, return code 8) when the abort occurs, all lines in that buffer for which no permission has been obtained (CONTROL 20) will be deleted from the active file.
CONTROL id-l,19,word-la
(0) (1) (15)
Causes WYLBUR to type one line of the active file at the terminal.
id-l terminal identifier
word-la WYLBUR line number (times 1000) to be written.
(15) = 0 Operation begun.
(15) = 0 Successful completion.
4 Line does not exist.
CONTROL id-l,20
(0) (1)
For a program using READ EDIT with the INFORM flag on, ensures that a changed line returned in a READ EDIT buffer with return code 8 still exists in the active file. If an abort should occur during processing of a READ EDIT multiple line buffer (return code 8) by the user program, WYLBUR deletes those lines contained in the buffer from the active file. Control 20 ensures that a line is retained in the active file and notifies the user program that an abort has occurred.
id-l terminal identifier
(15) = 0 Operation begun.
(15) = 0 Processing permission granted and recorded.
4 Processing permission denied because one or more
abort conditions have occurred since the
last READ EDIT buffer was returned.
READ id-l,location-la,length-la,control-la,MODE=TEXT
(0) (1) (15) (14)
Reads lines from the WYLBUR active file and places them in the user program area in one of several available formats.
id-l terminal identifier
location-la location of the area which is to receive the line(s)
length-la 1st 16 bits: zero (0) for codes 0/6, 100/106,
300/306,400/406
LRECL for codes 200/206, where
1<=LRECL<=235
2nd 16 bits; length of input area -
zero illegal
Codes 0/6 - if the PREST flag is
off in the WYLBUR mode word, data
may be lost if this length is
less than 240 bytes. If the PREST
flag is on in the WYLBUR mode word,
data may be lost if this length is
less than 256 bytes.
Codes 200/206 - Data may be lost if
this length is not a multiple of
LRECL.
Codes 300/306 - Data may be lost if
this length is not a multiple of 80.
Codes 400/406 - Data may be lost if
this length is not a multiple of 80.
control-la pointer to that area which contains information on
the line(s) to be read and the format in which the
requested data is to be returned by WYLBUR
Specifying area (bytes 1-2) : CODE MEANING
0 Read first line only.
1 Read line immediately
preceding first line.
2 Read line immediately
following first line.
3 Read line(s) from first
line to last line, if given.
4 Read line(s) from first line
to last line which contain
the given string. Stop at
last line if given. A zero
length string reads only
blank lines.
5 Read line(s) from first line
containing the given string
at the starting column. Stop
at ending line, if given.
6 Read line(s) from line
containing the given string
in columns from first
column thru last column.
Stop at last line, if given.
100/106 Similar to codes 0-6, but
only the line number(s) will
be returned. (NOTEXT)
200/206 Similar to codes 0-6, except
that only the text of the
line(s) will be returned,
truncated or padded to LRECL
characters per line. A
positive LRECL must be
supplied in the first 16
bits of the length-la
operand.
300/306 Similar to codes 200/206,
except that an LRECL=80 is
implied and positions 73/80
are replaced by the WYLBUR
line number in decimal
format.
400/406 Similar to code 300/306,
except that an LRECL=80 is
implied and positions 73/80
are replaced by the WYLBUR
line number in integer
format.
(all codes) bytes 3-4 : Maximum number of lines to be read.
Ignored for codes 0,1,2. A
zero means read lines until
the area is filled.
(all codes) bytes 5-8 : First WYLBUR line number (times
1000). A (-1) means, "read those
lines beginning with the line
following the last one read with
READ TEXT."
(codes 3,4,5,6) bytes 9-12 : Last WYLBUR line number (times
1000). A zero means "read lines
until last." 99999.999 is the
highest possible line number.
(codes 4,5,6) bytes 13-14 : First column, where 1<=FCOL<=235.
Ignored for code 4.
(codes 4,5,6) bytes 15-16 : Last column, where 1<=FCOL<=
LCOL<=235. Ignored for codes 4,5.
(codes 4,5,6) bytes 17-18 : String length. Must be non-zero
except for code 4.
(codes 4,5,6) bytes 19 on : String text, where 1<=FCOL+string
length-1<=235.
(15) = 0 Operation begun.
(15) = 0 Successful completion.
4 Specified line(s) not contained in the data set.
8 User area is too small.
(1) = Total number of bytes transferred.
(14) = Number of lines read.
AREA = CODES 0/6
For each line read, one set of the following:
bytes 1/4 : line number (times 1000)
byte 5 : number of text bytes in the line
bytes 6/L : line text
CODES 100/106
For each line read, one set of the following:
4 bytes : line number (times 1000)
CODES 200/206 and 300/306
For each line read, one set of the following:
LRECL bytes : line text adjusted to LRECL
For option codes 0/6, text will be returned in PREST or UNPREST format according the the setting of the PREST flag in the WYLBUR mode word in effect at the time of the READ TEXT call. For option codes 200/206 and 300/306, the PREST flag in the WYLBUR mode word is ignored and text is always returned unprest.
For option codes 3/6, 103/106, 203/206, 303/306 and 403/406, as many lines will be read as can be accomodated in the area as long as the total number of lines requested or the ending line number is not exceeded. For these codes, reading begins with the first line number equal to or greater than the starting line number. To read the entire active file, specify zero (0) as the starting line number. After each returned buffer has been processed, add one (1) to the last line number read and issue another READ TEXT until all lines have been read or use the -1 value in bytes 5/8.
WRITE id-l,location-la,length-la,lines-la,MODE=TEXT
(0) (1) (15) (14)
Writes or deletes specific lines in the WYLBUR active file.
id-l terminal identifier
location-la location of the area which contains the lines
in the specified format.
length-la 1st 16 bits: disposition code
Disposition codes:
0 Replace or insert line(s)
1 Replace line(s).
2 Insert line(s).
3 Delete line(s).
4 LRECL option (append only).
5 NUMBERED option (insert or append).
6 INTEGER option (insert or append).
2nd 16 bits: length of the area
lines-la for CODES 0,1,2,3,5,6: 1st 16 bits: zero
2nd 16 bits: number of lines
to be written or deleted.
for CODE 4:
1st 16 bits: LRECL, 1 <= LRECL <= 235
2nd 16 bits: number of lines to be written
AREA =
(CODES 0,1,2) For each line, one set of the following:
bytes 1/4 : line number (times 1000)
byte 5 : number of text bytes in the line
bytes 6/L : line text
(CODE 3) For each line, one set of the following:
bytes 1/4 : line number (times 1000)
(CODE 4) For each line, one set of the following:
bytes 1/LRECL : line text
(CODE 5) For each line, one set of the following:
bytes 1/72 : 72 bytes of line text
bytes 73/80 : 8-byte WYLBUR line number
in decimal format.
(CODE 6) For each line, one set of the following:
bytes 1/72 : 72 bytes of line text
bytes 73/80 : 8-byte WYLBUR line number
in INTEGER format.
(15) = 0 Operation begun.
(15) = 0 Successful completion.
4 Completed, line longer than WYLBUR length option.
8 Line truncated to 235 chars in WYLBUR.
12 No room in WYLBUR active file.
16 Line does not exist (REPLACE or DELETE).
20 Line already exists (INSERT).
24 Contents of area were invalid.
28 Line number too large for WYLBUR.
(15) = 12,16,20,24,28:
(1) = Residual byte count.
If register 15 returns a value of 12, 16, 20, 24 or 28, no indication that lines were either truncated or longer than the WYLBUR length option will be provided. Such a condition, however, does not cause the write to be canceled.
With codes 0, 1, and 2, text will be interpreted in PREST or UNPREST format in accordance with the current setting of the PREST flag in the WYLBUR mode word. For codes 4, 5, and 6, the setting of the PREST flag in the WYLBUR mode word is ignored and text is assumed to be UNPREST.
With disposition code 4, lines can only be appended to the active file. Each LRECL bytes will be used to create a new line. If the number of bytes is not an exact multiple of LRECL, register 15 will return the value 24 and a non-zero residual byte count will be returned in register 1. If the active file is empty, the line will be assigned the WYLBUR line number 1.000. If lines exist new lines will be assigned a line number which is the sum of the highest existing line number and the current WYLBUR delta value.
For disposition code 5, each 80-byte length is used to form a new line. The contents of positions 73/80, which must be valid WYLBUR line numbers, are used to number the line and insert it into the active file. If the number of bytes is not an exact multiple of 80, register 15 will return the value 24 and a non-zero residual byte count will be returned in register 1.
READ id-l,location-la,length-la[,write-la],MODE=EDIT
(0) (1) (15) (14)
Permits the program to relinquish control of the terminal to WYLBUR for command prompting and processing until an unrecognized command is entered from the terminal or, optionally, until a command is entered which causes changes to the active file.
id-l terminal identifier
location-la Location of the area which is to receive text
returned from WYLBUR. The text will either be
an unrecognized command in UNPREST format or,
optionally, a changed line(s) in the active file.
length-la Length of the area. UNPREST data may be lost if
less than 240 bytes. PREST data may be lost if
less than 256 bytes. Zero illegal.
write-la Location of an area containing a write line.
If a write operation is
specified, the write area
must contain an output line
with count as specified:
Field size: Contents:
2 bytes w (Length of line to be written
to terminal, where 0<w<163
w bytes Line to be written to terminal
(15) = 0 Operation begun.
(14) = 0 Typed command
= 1 Not-typed command
(15) = 0 Command was not recognized by WYLBUR.
(1) = Total number of bytes transferred. If zero, user
at terminal typed a question mark (?) and then ATTN
as a command to cause a Session Break to be scheduled.
AREA = The illegal command.
The following returns will only occur if the INFORM flag is on in the WYLBUR mode word and the command being processed is causing changes to the active file.
(15) = 4 A line, typed at terminal, was inserted into active
file. (COLLECT,INSERT)
(1) = Total number of bytes transferred.
(14) = 1 (number of lines inserted)
AREA = bytes 1/4 : line number inserted
byte 5 : number of text bytes in line
bytes 6/L : text or line inserted
(15) = 8 Line(s), not typed at terminal, were inserted into
active file. (USE, FETCH, COPY, ALIGN, JUSTIFY).
(1) = Total number of bytes transferred.
(14) = Number of lines transferred.
AREA = One set of the following for each line inserted:
bytes 1/4 : line number inserted
byte 5 : number of text bytes in the line
bytes 6/L : line text inserted
(15) = 12 A line, typed at terminal, was replaced in active
file. (REPLACE)
(1) = Total number of bytes transferred.
(14) = 1 (number of lines replaced)
AREA = bytes 1/4 : line number replaced
byte 5 : number of text bytes in line
bytes 6/L : line text replaced
(15) = 16 A line, not typed at terminal was replaced in active
file. (CHANGE, MODIFY, EDIT, CENTER)
(1) = Total number of bytes transferred.
(14) = 1 (number of lines replaced)
AREA = bytes 1/4 : line number replaced
byte 5 : number of text bytes in line
bytes 6/L : line text replaced
(15) = 20 One line was deleted, another inserted in active file
(MOVE).
(1) = Total number of bytes transferred.
(14) = 1 (number of lines inserted)
AREA = bytes 1/4 : line number deleted
bytes 5/8 : line number inserted
byte 9 : number of text bytes in line inserted
bytes 10/L : line text inserted line
(15) = 24 Line(s) were deleted from active file
(DELETE,ALIGN,JUSTIFY).
(1) = First line number deleted.
(14) = Last line number deleted.
(15) = 28 A CLEAR TEXT occurred in WYLBUR.
Illegal commands are returned one at a time in UNPREST format. All other returns listed occur only if the INFORM flag of the WYLBUR mode word is on.
When the INFORM flag is on, the following guide lines are applicable to the changes being reported:
- The text for changed lines is returned in either PREST or UNPREST format in accordance with the PREST flag setting in the WYLBUR mode word.
- If the NONUM flag is not set in the WYLBUR mode word, the NUMBER command will be allowed, but the changes in line numbers will not be reported.
- The user at the terminal may not issue a DELETE which specifies disjoint ranges. He must enter one command for each range to be deleted.
- The program may stop both the command in progress and all reporting of changes in "mid-stream" either explicitly or inadvertently by issuing a request to WYLBUR other than READ EDIT. A Session Break has the same effect upon a command in progress.
- For return codes 4, 12, 16, and 20, if the command causing the changes affects more than one line, each line will be reported one line at a time as soon as the line is changed, regardless of the specified size of the receive area. Before changing the next line, WYLBUR will wait for another READ EDIT request.
- On return code 8, WYLBUR will pass on each successive READ EDIT request as many changed lines as will fit in the program input area until all changes have been exhausted.
Before attempting to process a line in the input buffer, the user program should first issue a CONTROL 20 "permission" request. When permission is granted, the program is assured that the change reporting sequence has not been aborted due to a program panic or Session Break.
- When the command causing changes is the ALIGN or JUSTIFY command, each line to be split is first reported as a line which has been deleted, (return code 24), and on the next READ EDIT request, the new aligned or justified lines are reported as "not typed-inserted" lines (return code 8).
NOTE: In this form of READ EDIT, the user program receives no indication that all changes associated with a command have been reported. The next READ EDIT may cause WYLBUR to prompt the user for a new command. The user who wishes notification that all changes for a given command have been completed should use READ EDIT CHANGES.
READ id-l,location-la,length-la[,write-la],MODE=(EDIT,CHANGES)
(0) (1) (15) (14)
Allows the user program to receive control of the terminal once all changes to the active file caused by one command have been reported by WYLBUR.
Specifications are identical to those described for READ EDIT, except that a new return code is received by the user program. This return code indicates that all changes to the active file caused by a previous command have been completed.
All identical to those of READ MODE=EDIT.
(15) = 32 Changes completed.
NOTE:
This READ EDIT option may also be employed when a return code of 8 is issued on the WAIT following a WRITE EDIT request. A return code of 8 indicates that the INFORM flag in the WYLBUR mode word is on; the command passed with the WRITE EDIT will cause changes to the active file. This option allows the program to obtain changes via the READ EDIT mechanism without giving up control of the terminal once all changes caused by the command passed in the WRITE EDIT are reported.
WRITE id-l,location-la,length-la,code-la,MODE=EDIT
(0) (1) (15) (14)
Passes a command to WYLBUR and MILTEN for execution.
id-l terminal identifier
location-la location of the area containing the WYLBUR command
length-la length of the area, 1 < length < 163
code-la 0 the line has been typed at the terminal
nonzero the line has not been typed
The last 31 bits of the code-la register are reserved.
(15) = 0 Operation begun.
(15) = 0 Successful completion with no changes to the active
file.
4 Successful completion with changes to the active file.
This code is returned only if the INFORM and BLOCK
flags in the WYLBUR mode word are off.
8 Active file changes pending, issue READ MODE=(EDIT,
CHANGES) next. This code is returned only if the
INFORM flag is on and the BLOCK flag is off in the
WYLBUR mode word.
-4 Active file changes prohibited. This code is returned
only if (1) a BLOCK, NONUM, or NOALGN flag is on in the
WYLBUR mode word and (2) command execution would
violate that flag.
-8 An error was detected and an error message was
typed on the terminal. If code-la was set,
then the command was also typed with the message.
(1) = 0 No write/idle attention outside ORVYL.
4 Write/idle attention outside ORVYL and Session Break
was scheduled.
WARNING: If a return code 8 from WAIT is followed by any command to WYLBUR other than a READ EDIT or READ EDIT with CHANGES, then the changes to the active file will be aborted.
MILCOM id-l,location-la,length-la,code-la
(0) (1) (15) (14)
Passes a string to MILTEN to be used as the text for a WTO to the operator's console or as a command to be executed directly by MILTEN.
id-l terminal identifier
location-la location of the area which contains
the string
length-la length of the area, 1 <length < 163
code-la
Code: Meaning:
0 Command input from terminal
1 Command input was not from
the terminal
2 String to be used in WTO to the
operator
(15) = 0 Operation begun
(15) = 0 Successful completion
4 String was used as a command but an error
was detected and INVALID message typed. If
code-la was 1, the incorrect command
was also typed.
8 Command passed was the name of a subsystem.
Control was not passed to the subsystem. Use
WRITE, MODE=EDIT or COMMAND, MODE=WYLBUR to
pass control to the subsystem.
(1) = 0 No write/idle ATTN outside ORVYL.
4 Write/idle ATTN outside ORVYL.
ATTACH 2,location-la,length-la[,MODE=([SHARE][,OLD][,WAIT])]
(0) (1) (15)
Requests the use of a file.
location-la Location of the area containing the file name.
Zero if a temporary file.
length-la Length of the area. Zero if a temporary file.
MODE=SHARE Other tasks may attach the file at the same time.
MODE=OLD The file already exists. If this option is not
specified, a new file will be created.
MODE=WAIT If the file cannot be immediately attached, the
program will wait for it to become available.
(15) = 0 Operation begun.
4 Attach was already begun.
8 Device was already attached not MODE=SHARE.
12 Device was already attached MODE=SHARE.
-4 Too many devices attached.
-8 Device name illegal.
-12 ORVYL file system unavailable.
(0) = 32-bit file identifier
The valid file identifier is returned in register zero (0) when the return in register 15 is 0, 4, 8 or 12.
(15) = 0 Attach completed.
-4 File not immediately available.
4 Access not permitted.
8 File storage limit exceeded (not MODE=OLD).
12 No space remains in file directory.
16 File does not exist (MODE=OLD)
20 File already exists (not MODE=OLD).
24 System tables overflowed.
28 File space exhausted (not MODE=OLD).
32 File may only be attached MODE=SHARE.
READ id-l,location-la,length-la,block-la[,MODE=([WAIT][,SKIP])]
(0) (1) (15) (14)
Reads a data block from a file.
id-l file identifier
location-la Location of the area which is to receive the block
length-la Length of the area. Maximum area size is 8192
bytes. Blocks will be read until
this area is filled.
block-la The number of the first block to be read. Block
numbers start at zero.
MODE=WAIT If the request cannot be immediately processed, the
program will wait for the file to become available.
MODE=SKIP If the requested block does not exist, then the
next existing block should be read instead.
(15) = 0 Operation begun.
-12 ORVYL file system not available.
(15) = 0 Successful completion.
-4 Permanent I/O Error.
4 File not immediately available.
8 READ access to this file prohibited.
12 Block does not exist.
(1) = Number of bytes read.
(14) = Number of last block processed, plus one.
Note: The number of bytes read will be no greater than the length of the area. If a block written using less than 2048 bytes is read, another block will not be read, regardless of the total size of the area. Contents of the area specified, but not filled, remain undefined. See 5.10.3 for core storage restrictions.
WRITE id-l,location-la,length-la,block-la[,MODE=WAIT]
(0) (1) (15) (14)
Writes a data block to a file.
id-l file identifier
location-la location of the area containing the block
length-la Length of the area. The maximum area size is
8192 bytes. (See note.) Blocks will be written
until the area is emptied.
block-la block number or beginning block number
MODE=WAIT If the request cannot be immediately processed, the
program will wait for the file to become available.
(15) = 0 Operation begun.
-12 ORVYL file system not available.
(15) = 0 Successful completion.
-4 Permanent I/O error.
4 File not immediately available.
8 WRITE access to this file prohibited.
12 Rewriting an existing block not permitted.
16 File storage limit exceeded.
20 File space exhausted.
24 Block out-of-range.
(1) = Number of bytes transmitted.
(14) = Number of last block processed, plus one.
NOTE: Core storage in ORVYL is divided into pages of 4096 bytes each. A buffer area must begin on a double-word boundary and may not cross more than one page boundary. If a page boundary is crossed the buffer must extend at least 8 bytes onto the second page. Thus, a buffer of 4096 bytes or less may begin on any double-word. A buffer of 6144 bytes may begin as much as 2048 bytes from the beginning of a page, while an 8192 byte buffer must begin on a page boundary. For maximum efficiency, buffers of 4096 bytes or less should reside on a single page.
CONTROL id-l,0,block-la[,MODE=WAIT]
(0) (1) (15)
Creates a file data block of undefined content.
id-l file identifier
block-la block number
MODE=WAIT If the request cannot be immediately processed, the
program will wait for the file to become available.
(15) = 0 Operation begun.
-12 ORVYL file system not available.
(15) = 0 Successful completion.
-4 Permanent I/O error.
4 File not immediately available.
8 Access not permitted.
12 Block already exists.
16 File storage limit exceeded.
20 File space exhausted.
CONTROL id-l,1,block-la[,MODE=WAIT]
(0) (1) (15)
Deletes a file data block.
id-l file identifier
block-la block number
MODE=WAIT If the request cannot be immediately processed, the
program will wait for the file to become available.
(15) = 0 Operation begun.
-12 ORVYL file system not available.
(15) = 0 Successful completion.
-4 Permanent I/O Error.
4 File not immediately available.
8 Access not permitted.
12 Block does not exist.
CONTROL id-l,2,first-la,last-la[,MODE=WAIT]
(0) (1) (15) (14)
Deletes a range of file data blocks.
id-l file identifier
first-la first block number
last-la last block number
MODE=WAIT If the request cannot be immediately processed, the
program will wait for the file to become available.
(15) = 0 Operation begun.
-12 ORVYL file system not available.
(15) = 0 Successful completion.
-4 Permanent I/O error.
4 File not immediately available.
8 Access not permitted.
12 Not all blocks in the range exist.
(1) Number of blocks deleted.
CONTROL id-l,3,block-la[,MODE=WAIT]
(0) (1) (15)
Tests for the presence of a file block.
id-l file identifier
block-la block number
MODE=WAIT If the request cannot be immediately processed, the
program will wait for the file to become available.
(15) = 0 Operation begun.
-12 ORVYL file system not available.
(15) = 0 Specified block present.
-4 Permanent I/O error.
4 File not immediately available.
8 Access not permitted.
12 Block not present.
CONTROL id-l,4[,MODE=WAIT]
(0) (1)
Reports the first block number in the file.
id-l file identifier
MODE=WAIT If the request cannot be immediately processed, the
program will wait for the file to become available.
(15) = 0 Operation begun.
-12 ORVYL file system not available.
(15) = 0 Successful completion.
-4 Permanent I/O error.
4 File not immediately available.
8 Access not permitted.
12 No blocks in file.
(1) = Number of first block in the file.
CONTROL id-l,5[,MODE=WAIT]
(0) (1)
Reports the last block number in the file.
id-l file identifier
MODE=WAIT If the request cannot be immediately processed, the
program will wait for the file to become available.
(15) = 0 Operation begun.
-12 ORVYL file system not available.
(15) = 0 Successful completion.
-4 Permanent I/O error.
4 File not immediately available.
8 Access not permitted.
12 No blocks in file.
(1) = Number of last block in the file.
CONTROL id-l,6[,MODE=WAIT]
(0) (1)
Reports the total number of blocks in the file.
id-l file identifier
MODE=WAIT If the request cannot be immediately processed, the
program will wait for the file to become available.
(15) = 0 Operation begun.
-12 ORVYL file system not available.
(15) = 0 Successful completion.
-4 Permanent I/O error.
4 File not immediately available.
8 Access not permitted.
(1) = Number of user-written blocks in the file.
(14) = Number of billable blocks in the file, including
both user blocks and system index blocks.
This control now does nothing. All file indexes are automatically updated when necessary. It is only kept for backward compatability.
CONTROL id-l,7[,MODE=WAIT]
(0) (1)
Updates the index for the file. Ensures that all file updates are retained in case of system error.
id-l file identifier
MODE=WAIT If the request cannot be immediately processed, the
program will wait for the file to become available.
(15) = 0 Operation begun.
-12 ORVYL file system not available.
(15) = 0 Successful completion.
-4 Permanent I/O error.
4 File not immediately available.
8 Access not permitted.
CONTROL id-l,8,location-la[,length-la][,MODE=WAIT]
(0) (1) (15) (14)
Erases or renames files. This macro may be used to erase or rename a file only if the file is not attached with MODE=SHARE. The file is detached only if it is successfully scratched, otherwise it remains attached. A DETACH following a successful scratch will result in an error.
id-l file identifier
location-la location of the area containing the new file name.
If no name is specified (i.e., if R15=0), the file
will be erased.
length-la length of the file name.
MODE=WAIT If the request cannot be immediately processed, the
program will wait for the file to become available.
(15) = 0 Operation begun.
-4 File attached MODE=SHARE.
-8 New name illegal.
-12 ORVYL file system not available.
4 Attempt to change file owner during rename.
(15) = 0 Successful completion.
-4 Permanent I/O error.
4 File not immediately available.
8 Access not permitted.
12 New file name already exists.
16 No space available in file directory.
CONTROL id-l,9,access-la[,user-la]
(0) (1) (15) (14)
Assigns and withdraws access privileges for a file. Changes in file access privileges for any user do not affect that user if the file is attached when the change is made. If user is not specified, then the FILEMASK is altered. Only the file owner may alter the FILEMASK.
id-l file identifier
access-la code specifying the permitted access
bits 29-31 000 no access
001 read only
111 read and write
011 read and append
010 append only
bit 28 0 may not extend access to others
1 may extend access to others
user-la location of the 6-byte area containing the name of
the user to whom access is to be permitted (i.e., gg.uuu).
If no user is specified, the FILEMASK is altered.
(15) = 0 Operation begun.
-4 File attached MODE=SHARE.
-8 Illegal user.
-12 ORVYL file system not available.
4 Non-owner attempt to alter owner's privileges.
(15) = 0 Successful completion.
-4 Permanent I/O error.
4 File not immediately available.
8 Attempt to extend more privileges than user himself
has.
12 Attempt to extend privileges to a user who
has not been validated for ORVYL file use.
16 No space remains in file directory.
CONTROL id-l,10,access-la
(0) (1) (15)
Assigns and withdraws the access privileges for a file to all valid terminal users. Changes in PUBLIC access privileges may only be made by the file owner. If the file was attached MODE=SHARE, a change to public privileges will not affect those users attached to the file when the change was made.
id-l file identifier
access-la code specifying the permitted access
bits 29-31 000 no access
001 read only
111 read and write
011 read and append
010 append only
bits 0-28 not used
(15) = 0 Operation begun.
4 Attempt to alter public privileges by non-owning
user.
-12 ORVYL file system not available.
(15) = 0 Successful completion.
CONTROL id-l,11[,location-la,length-la]
(0) (1) (15) (14)
Reports the FILEMASK and PUBLIC access privileges for a file. If the issuer is the file owner or a user with EXTEND privileges, also reports all other users with access to the file as well as the access privileges each user enjoys. Otherwise, only the owner, PUBLIC, and issuing user privileges, if any, are reported.
id-l file identifier
location-la Location of the area which is to receive the names
of the users with privileges and the access
privileges. If no location is given, only the
PUBLIC and owner's privileges will be reported.
length-la length of the area (at least 7 bytes)
(15) = 0 Operation begun.
-12 ORVYL file system not available.
(15) = 0 Successful completion.
-4 Permanent I/O error.
(1) Public and FILEMASK:
Public privileges:
bits 21-23 000 no access
001 read only
111 read and write
011 read and append
010 append only
FILEMASK:
bits 29-31 000 no access
001 read only
111 read and write
011 read and append
010 append only
(14) Number of privileged users.
AREA = 7 bytes for each privileged user:
bytes 1-6: user name (i.e., gg.uuu)
7: user privileges:
bits 5-7 000 no access
001 read only
111 read and write
011 read and append
010 append only
bit 4 0 may not permit access to others
1 may permit access to others
Privileged users will be reported until the specified area is filled.
CONTROL id-l,12,state-la
(0) (1) (15)
Specifies that a file may or may not be attached only with MODE=SHARE. Changes in the SHARE ONLY ATTACH condition may only be made by the file owner. The SHARE ONLY condition may be specified even when the file is currently attached (not MODE=SHARE); in this case, SHARE ONLY takes effect after the file is next detached.
id-l file identifier
state-la zero, file may be attached normally
non-zero, file may be attached only MODE=SHARE
(15) = 0 Operation begun.
4 Attempt to alter SHARE ONLY ATTACH condition by
non-owning user.
-12 ORVYL file system not available.
(15) = 0 Successful completion.
Note: SHARE ONLY prevents exclusive file use, but does not prevent file updating by a program using the RESERVE and RELEASE macros.
CONTROL id-l,13
(0) (1)
Senses the ATTACH condition for a file.
id-l file identifier
(15) = 0 Operation begun.
-12 ORVYL file system not available.
(15) = 0 File may be attached normally.
4 File may be attached only MODE=SHARE.
CONTROL id-l,14,info-la[,MODE=(FORMAT,WAIT)]
(0) (1) (15)
Writes the file format field (4 bytes) in the file directory entry for the specified file. This field may be employed by any user program, but is used primarily by the Command Language Processor to retain the format (e.g., EDIT,CARD,LRECL,etc.) in which the file is stored. WRITE access privilege is required in order to modify the file format field.
id-l file identifier
info-la information to be written
in the file directory entry
MODE=FORMAT Sets the FORMAT entry for the file.
(15) = 0 Operation begun
-12 File system not available
(15) = 0 Information written in the file
directory entry.
-12 File system not available.
4 File not immediately available.
8 Access not permitted.
byte 1 TYPE = X'80' Library
X'40' Loadfile (plus Library)
X'04' Fixed LRECL=nn
X'05' Numbered (LRECL=nn)
X'06' Integer (LRECL=nn)
X'01' Edit
X'02' Variable
byte 2 Reserved for URAM use
bytes 3-4 LRECL
CONTROL id-l,15
(0) (1)
Retrieves the file format field (4 bytes).
id-l file identifier
(15) = 0 Operation begun
-12 File system not available
(15) = 0 FORMAT option set
12 FORMAT option not set
-12 File system not available
(1) = 4 bytes of file format information
byte 1 TYPE = X'80' Library
X'40' Loadfile (plus Library)
X'04' Fixed LRECL=nn
X'05' Numbered (LRECL=nn)
X'06' Integer (LRECL=nn)
X'01' Edit
X'02' Variable
byte 2 Reserved for URAM use
bytes 3-4 LRECL
CONTROL id-l,16,state-la
(0) (1) (15)
Sets the CLP/NOCLP condition for a file. If NOCLP is set, the terminal user cannot ERASE, PUT, RENAME, SET PERMIT, SHOW FILES ERASE, or DEFLATE the specified file. Only the file owner may set or reset this condition.
id-l file identifier
state-la 0 - all CLP commands may be performed for the
file (CLP).
1 - CLP may not modify the file (NOCLP).
(15) = 0 Operation begun
4 Attempt to alter CLP/NOCLP condition by a
non-owning user
-12 File system not available
(15) = 0 Operation successful
CONTROL id-l,17
(0) (1)
Senses the CLP/NOCLP condition set for a file.
id-l file identifier
(15) = 0 Operation begun
-12 ORVYL file system not available
(15) = 0 Any CLP command may be executed (CLP).
4 CLP may not modify the file (NOCLP).
CONTROL id-l,18,state-la
(0) (1) (15)
Sets the CLP only condition for a file. If set, only CLP can ERASE, PUT, RENAME, SET PERMIT, SHOW FILES ERASE, or SHRINK the specified file. Only the file owner may set or reset this condition.
id-l file identifier
state-la 0 - all CLP commands may be performed for the
file (CLP).
1 - CLP may not modify the file (NOCLP).
(15) = 0 Operation begun
4 Attempt to alter CLP/NOCLP condition by a
non-owning user
-12 File system not available
(15) = 0 Operation successful
CONTROL id-l,19
(0) (1)
Senses the CLP only condition for a file.
id-l file identifier
(15) = 0 Operation begun
-12 ORVYL file system not available
(15) = 0 Normal mode.
12 CLP only mode.
CONTROL id,20
(0) (1)
Sense a file type (non-indexed or normal).
(15) = 0 Operation begun
(15) = 0 Normal file structure
12 Non-indexed file structure
28 Hybrid file structure
CONTROL id,21
(0) (1)
Set SPIRES only.
(15) = 0 Operation begun
(15) = 0 Successful completion
CONTROL id,22
(0) (1)
Sense SPIRES only mode.
(15) = 0 Operation begun
(15) = 0 Normal mode
12 SPIRES only mode
CONTROL id,23
(0) (1)
Sense the file block size (2K or 4K).
(15) = 0 Operation begun
(15) = 0 Successful completion (1) = block size in bytes
CONTROL id,24
(0) (1)
Obtain maximum file size in blocks.
(15) = 0 Operation begun
(15) = 0 Successful completion (1) = Maximum file size in blocks
CONTROL id,25,count
(0) (1) (15)
where count is the maximum file size in blocks.
Convert the file to a hybrid file. Any file type can be converted, including converting a hybrid file to a larger hybrid file. Count must be large enough to contain the current file size.
(15) = 0 Operation begun
(15) = 0 File converted
12 Attempted to truncate existing file
16 User file space exceeded
20 Contiguous IXRs could not be allocated
STATUS 0,access-la,usera-la[,userb-la]
(0) (1) (15) (14)
Assigns and withdraws global file access privileges for all files owned by a user. Changes made in access privileges do not affect access to any files in use at the time the change is made.
access-la code specifying the permitted access
bits 29-31 000 no access
001 read only
111 read and write
011 read and append
010 append only
bit 28 0 may not extend access to others
1 may extend access to others
usera-la location of the 6-byte area which contains the name
of the user to whom access is to be permitted.
userb-la location of the 6-byte area which contains the
name of the file owner. If none is given, the
current user is implied.
(15) = 0 Operation begun.
-4 Too many devices attached.
-8 Account name illegal.
-12 ORVYL file system unavailable.
4 Attempt to extend privileges to owner.
(0) = 32-bit device identifier (used only for WAIT).
(15) = 0 Successful completion.
4 Attempt to extend more privileges than the user
himself has.
8 Attempt to extend privileges to a user who has
not been validated for ORVYL file use.
12 Attempt to extend privileges by a user who has
not been validated for ORVYL file use.
16 No space available in file directory.
STATUS 1,access-la
(0) (1)
Assigns and withdraws global file access for all the files owned by a user to all validated terminal users. Changes in PUBLIC access may only be made by the file owner.
access-la code specifying permitted access
bits 29-31 000 no access
001 read only
111 read and write
011 read and append
010 append only
(15) = 0 Operation begun.
-4 Too many devices attached.
-12 ORVYL file system unavailable.
(0) = 32-bit device identifier (used only for WAIT).
(15) = 0 Successful completion.
STATUS 2,location-la,length-la[,name-la]
(0) (1) (15) (14)
Reports the names, creation dates and last reference dates of a user's files. Files are reported in alphabetical order. Only permitted users may list file names of other users.
location-la location of the area which is to receive the file
names and dates
length-la length of the area (at least 56 bytes)
name-la 40-byte area containing:
bytes 1-6: name of the file owner
7: period (.)
8-40: filename (padded with blanks)
NOTE: If bytes 7-40 or 8-40 are blank,
reporting will begin with the
first file. If a matching file
name is not encountered,
reporting will begin with the
next file name encountered in
collating sequence order. If
user is not given, the issuing
user is assumed.
(15) = 0 Operation begun.
-4 Too many devices attached.
-8 Name illegal.
-12 ORVYL file system unavailable.
(0) = 32-bit device identifier (used only for WAIT).
(15) = 0 Successful completion.
4 Account has not been validated for ORVYL file use.
8 No files exist to be reported.
12 Reading file names prohibited.
16 No files exist in higher collating sequence.
(1) Number of file names reported.
AREA = 56 bytes for each file name reported:
bytes 1-44: ORV.gg.uuu.filename
45-50: creation date (YYMMDD)
51-56: last reference date (YYMMDD)
File names will be reported until the area is filled.
STATUS 3,location-la,length-la[,user-la]
(0) (1) (15) (14)
Reports privileged users as well as the access privileges each user is assigned. Users are reported in alphabetical sequence. Only the file owner and users with EXTEND privileges may report other users. Users without EXTEND privileges may sense only their own access privileges.
location-la location of the area which is to receive the
user names and access privileges
length-la length of the area (at least 7 bytes)
user-la 6-byte area containing the name of the user
If a user is not given, the current user
is assumed.
(15) = 0 Operation begun.
-4 Too many devices attached.
-8 Name illegal.
-12 ORVYL file system unavailable.
(0) = 32-bit device identifier (used only for WAIT).
(15) = 0 Successful completion.
4 Account does not exist.
8 Reporting privileged users prohibited.
(1) Public privileges:
bits 21-23 000 no access
001 read only
111 read and write
011 read and append
010 append only
(14) Number of users sensed.
AREA = 7 bytes for each user sensed:
bytes 1-6: user
7: user's privileges:
bits 5-7 000 no access
001 read only
111 read and write
011 read and append
010 append only
bit 4 0 may not extend access
to others
1 may extend access to
others
bits 0-3 not used
Users will be reported until the area is filled.
STATUS 4[,user-la]
(0) (1)
Reports the space allocated to and the current space usage of a user. Only permitted users may report space status.
user-la 6-byte area containing the user name. If no
user is given, the current user is assumed.
(15) = 0 Operation started.
-4 Too many devices attached.
-8 Account name illegal.
-12 ORVYL file system unavailable.
(0) = 32-bit device identifier (used only for WAIT).
(15) = 0 Successful completion.
4 Account has not been validated for ORVYL file use.
8 Sensing this user's space prohibited.
(1) Space allotment (number of blocks).
(14) Space used (number of blocks).
STATUS 5,location-la,length-la,blocks-la
(0) (1) (15) (14)
Extends a Non-IXR file by adding blocks to the end if enough contiguous blocks happen to be available. It reports how many blocks would be possible to extend the file if the requested amount is not possible. These blocks are not reserved however so even these might no longer be available if one does not act quickly.
location-la address of filename length-la length of filename blocks-la number of blocks to extend this file.
(15) = 0 Operation started
-4 Too many devices attached
-8 Invalid filename
-12 ORVYL file system unavailable
(0) = 32-bit device identifier (used only for WAIT).
(15) = 0 Successful completion
4 Not possible
(1) If 15 = 4 then contains the count of blocks
possible.
STATUS 6,location-la,length-la,blocks-la
(0) (1) (15) (14)
Allocate a Non-IXR file (Non-indexed file).
location-la address of filename length-la length of filename blocks-la number of blocks to allocate for this file.
(15) = 0 Operation started
-4 Too many devices attached
-8 Invalid filename
-12 ORVYL file system unavailable
(0) = 32-bit device identifier (used only for WAIT).
(15) = 0 Successful completion
4 Account not valid
8 User block limit exceeded
12 File directory full
16 Access not permitted
20 File already exists
24 Insufficient file system space
28 Non-IXR files not allowed.
STATUS 7,location-la,length-la,blocks-la
(0) (1) (15) (14)
Allocate a Hybrid file (Consecutive IXR file).
location-la address of filename length-la length of filename blocks-la number of blocks to allocate for this file.
(15) = 0 Operation started
-4 Too many devices attached
-8 Invalid filename
-12 ORVYL file system unavailable
(0) = 32-bit device identifier (used only for WAIT).
(15) = 0 Successful completion
4 Account not valid
8 User block limit exceeded
12 File directory full
16 Access not permitted
20 File already exists
24 Insufficient file system space
28 Hybrid files not allowed.
The following STATUS macros are reserved for systems programmers only. They can be used for the development of utilities or for testing system changes.
STATUS 100,location-la
(0) (1)
Creates a new account for the file system designated by the group code part of the account being created.
location-la address of account in the format GG.UUU or UUU$GG
(15) = 0 Operation started
-4 Too many devices attached
-8 Invalid account format
-12 ORVYL file system unavailable
(0) = 32-bit device identifier (used only for WAIT).
(15) = 0 Successful completion
4 Account already exists
8 No more room in catalog
STATUS 101,location-la
(0) (1)
Deletes an account from the file system designated by the group code part of the account being deleted.
location-la address of account in the format GG.UUU or UUU$GG
(15) = 0 Operation started
-4 Too many devices attached
-8 Invalid account format
-12 ORVYL file system unavailable
(0) = 32-bit device identifier (used only for WAIT).
(15) = 0 Successful completion
4 Account does not exist
8 Can't delete an account with files
STATUS 102,location-la,space-la
(0) (1) (15)
Resets the maximum count of blocks that can be used by the account.
location-la address of account in the format GG.UUU or UUU$GG space-la count of blocks
(15) = 0 Operation started
-4 Too many devices attached
-8 Invalid account format
-12 ORVYL file system unavailable
(0) = 32-bit device identifier (used only for WAIT).
(15) = 0 Successful completion
4 Account does not exist
STATUS 103,location-la,length-la,start-la
(0) (1) (15) (14)
Lists the accounts in a file system, sorted alphabetically.
location-la address of output area
length-la length of output area, must be at least 14
start-la byte 1 = file system id
bytes 2-4 is the address of the start account
location
(15) = 0 Operation started
-4 Too many devices attached
-8 Invalid account format
-12 ORVYL file system unavailable
(0) = 32-bit device identifier (used only for WAIT).
(15) = 0 Successful completion
4 No more accounts after start account.
(1) = count of accounts listed
Output area = 14 bytes for each account listed:
bytes 1-6 is the account bytes 7-10 is the maximum count of blocks allowed bytes 11-14 is the current count of blocks used
The output area will be filled with accounts until it is full or the last account in the file system has been listed. If the start account is blank, the list will start from the first account in the file system.
STATUS 104,location-la,space-la
(0) (1) (15)
Resets the space used for an account. This may be necessary in the event of an Orvyl failure causing a space update to be lost.
location-la address of account in GG.UUU or UUU$GG format space-la count of blocks
(15) = 0 Operation started
-4 Too many devices attached
-8 Invalid account format
-12 ORVYL file system unavailable
(0) = 32-bit device identifier (used only for WAIT).
(15) = 0 Successful completion
4 Account does not exist
See the FBAL command which uses this macro.
STATUS 105,location-la,length-la
(0) (1) (15)
Deletes a file catalog entry without releasing blocks. This may be necessary if a file becomes corrupted and the blocks can not be released normally. The blocks referenced by the deleted entry become lost blocks which then can be reclaimed. Note that the blocks allocated for the account is not updated.
location-la address of file name length-la length of file name
(15) = 0 Operation started
-4 Too many devices attached
-8 Invalid file name
-12 ORVYL file system unavailable
(0) = 32-bit device identifier (used only for WAIT).
(15) = 0 Successful completion
4 File does not exist
STATUS 106,location-la,length-la,block-la
(0) (1) (15) (14)
Reads a real block from a file system. This function is used in testing system changes or for reparing damaged records. This macro can be used when the file system is otherwise unavailable.
location-la address of output area
length-la length of output area, must be at least 4 and
not more than the file system block size (2k
or 4k). Generally one would used the file
system block size.
block-la byte 1 = file system id
bytes 2-4 is the real block number to read
(15) = 0 Operation started
-4 Too many devices attached
(0) = 32-bit device identifier (used only for WAIT).
(15) = 0 Successful completion
(1) bytes 1-2 record type
X'00FF' File System Master Block
X'0080' Catalog
X'0040' Bit Map
X'0010' ZIXR (Hybrid index)
X'0008' IXR (Index)
X'0004' SIXR (Super index)
X'0002' MIXR (Master index)
X'0001' User data block
bytes 3-4 = length of record
STATUS 107,location-la
(0) (1)
Sets the file access account to the account specified instead of the logged on account or to clear previously set pseudo account
location-la address of account in the format GG.UUU or UUU$GG
or zero to clear pseudo account
(15) = 0 Operation started
-4 Too many devices attached
-8 Invalid account format
(0) = 32-bit device identifier (used only for WAIT).
(15) = 0 Successful completion
STATUS 108,location-la,mode-la
(0) (1) (15)
Sets the file system access mode (read/write, read only, no access)
location-la address of file system name (8 bytes,
space filled) or the file system id
mode-la 0 change from read only to read/write
4 change from read/write to read only
8 change from no access to read/write
12 change from read/write to no access
(15) = 0 Operation started
4 File system already in desired mode
12 Invalid mode specified
-4 Too many devices attached
-8 Invalid file system name
(0) = 32-bit device identifier (used only for WAIT).
(15) = 0 Successful completion
STATUS 109,location-la,length-la,block-la
(0) (1) (15) (14)
Writes a real block to a file system. This function is used in testing system changes or for reparing damaged records. This macro can be used when the file system is otherwise unavailable.
location-la address of input area
length-la bytes 1-2 = record type
X'00FF' File System Master Block
X'0080' Catalog
X'0040' Bit Map
X'0010' ZIXR (Hybrid index)
X'0008' IXR (Index)
X'0004' SIXR (Super index)
X'0002' MIXR (Master index)
X'0001' User data block
bytes 3-4 = length of input area, must
be at least 4 and not more than the file
system block size (2k or 4k).
block-la byte 1 = file system id
bytes 2-4 is the real block number to write
(15) = 0 Operation started
-4 Too many devices attached
(0) = 32-bit device identifier (used only for WAIT).
(15) = 0 Successful completion
STATUS 110,location-la,length-la,block-la
(0) (1) (15) (14)
Udates the start block number in the catalog for a file entry. This can be used to relocate a file.
location-la address of file name length-la length of file name block-la new block number
(15) = 0 Operation started
-4 Too many devices attached
-8 Invalid file name
-12 ORVYL file system unavailable
(0) = 32-bit device identifier (used only for WAIT).
(15) = 0 Successful completion
4 File does not exist
STATUS 111,location-la,length-la,area-la
(0) (1) (15) (14)
Reads the catalog entry for an account or file. This is usefull to determine the first block of a file for use with STATUS 106 or testing sytem changes. Catalog entry formats are described by the NTRY dsect.
location-la address of output buffer
length-la length of output buffer
area-la 40 byte space filled area containing the
account in GG.UUU format or the file name in
GG.UUU.aaaaaaa ... format.
(15) = 0 Operation started
-4 Too many devices attached
-8 Invalid file/account name
(0) = 32-bit device identifier (used only for WAIT).
(15) = 0 Successful completion
4 File/account does not exist
STATUS 112,location-la,length-la,fsid-la
(0) (1) (15) (14)
Given file system id or name, return both.
location-la address of output buffer of at least 9 bytes
length-la length of output buffer
fsid-la address of 8 byte, space filled file system
name or file system id
(15) = 0 Operation started
-4 Too many devices attached
-8 Invalid file system name or id
(0) = 32-bit device identifier (used only for WAIT).
(15) = 0 Successful completion
The output buffer will contain a one byte id followed by the eight byte name.
STATUS 113,location-la,length-la,group-la
(0) (1) (15) (14)
Given group code, return file system id and name.
location-la address of output buffer of at least 9 bytes length-la length of output buffer group-la address of 2 byte group code
(15) = 0 Operation started
-4 Too many devices attached
-8 Invalid group code
-12 Group not defined for any file system
(0) = 32-bit device identifier (used only for WAIT).
(15) = 0 Successful completion
The output buffer will contain a one byte id followed by the eight byte name.
STATUS 114,location-la,length-la
(0) (1) (15)
Moves the file system/group table to the output area. Returns the count of file systems so that the table can be interpreted.
location-la address of output area
length-la length of output area of at least 936
(26*36) bytes
(15) = 0 Operation started
-4 Too many devices attached
(0) = 32-bit device identifier (used only for WAIT).
(15) = 0 Successful completion
(1) = Count of file systems
STATUS 115,location-la,length-la,block-la
(0) (1) (15) (14)
Reads a real block header from a file system. This function is used in testing system changes. This macro can be used when the file system is otherwise unavailable. The block header format is described by the FBHDR dsect.
location-la address of output area
length-la length of output area, must be at least 4 and
not more than 32.
block-la byte 1 = file system id
bytes 2-4 is the real block number to read
(15) = 0 Operation started
-4 Too many devices attached
(0) = 32-bit device identifier (used only for WAIT).
(15) = 0 Successful completion
(1) length of block header
STATUS 116,count-la
(0) (1)
Gets a contiguous range of blocks from a file system. Note that a count of one block can be specified.
count-la byte 1 File system id
bytes 2-4 Count of contiguous blocks
(15) = 0 Operation started
-4 Too many devices attached
-8 Invalid file system id
-12 ORVYL file system unavailable
(0) = 32-bit device identifier (used only for WAIT).
(15) = 0 Successful completion
4 Not possible
(1) = First block in range of contiguous blocks
STATUS 117,time-la
(0) (1)
Suspends program execution for time interval specified in 0.1 second increments.
time-la Time interval specified in number of 0.1 seconds
(15) = 0 Operation started
-4 Too many devices attached
(0) = 32-bit device identifier (used only for WAIT).
(15) = 0 Successful completion
The timer starts as soon as the STATUS SVC is issued. The program will receive control back from WAIT as soon as the time has expired or immediately if the timer had already expired before the WAIT was issued.
RESERVE id-l[,MODE=WAIT]
(0)
Obtain exclusive control of a file which is attached with MODE=SHARE.
id-l file identifier
MODE=WAIT If exclusive control cannot be immediately obtained,
the program will wait until control can be obtained.
(15) = 0 Operation started.
(15) = 0 Exclusive control obtained.
4 Exclusive control not immediately available.
8 WRITE access to this file prohibited.
RELEASE id-l
(0)
Relinquishes exclusive control previously obtained by RESERVE.
id-l file identifier
(15) = 0
(15) = 0
ATTACH 4,location-la,length-la[,return-la][,MODE=([WAIT][,CONTROL])]
(0) (1) (15) (14)
Requests the creation and opening of a SUZAN path. For further information on SUZAN, see the User's Guide to SVCCOM. (SVCCOM is the development system for SUZAN.)
location-la Location of the area containing the path tags and
password. Area is 20 bytes long and contains the
8-byte identifier for the user's side of the path,
the 8-byte identifier for the other side of the path,
and the 4-byte password for the path.
The two identifiers may not be the same nor
may they begin with hexidecimal 255 (X'FF').
length-la 1st 16-bits: number of seconds to wait before
TIME-OUT (600 maximum) or zero.
If TIME-OUT is specified, MODE=WAIT
must also be specified.
2nd 16-bits: length of buffer to be allocated
by the system for the path. This
length must be at least as large
as the longest transaction to be
received by the user (maximum
8192).
return-la Location of a 9-byte area where information will be
placed if there is a path name conflict (as defined
in the SUZAN documentation).
Byte 1 contains the duplicate-path-names flags from
the PATHMFL field of the PATH block
Bytes 2-9 contain the jobname of the conflicting
path.
MODE=WAIT The program will wait until a path device is
available and the other side of the path has
been opened. If the timeout value is zero,
the program will wait indefinitely for the
path to be completed. If the time interval
is not zero and the time interval expires
before the path can be opened, the return
code in register 15 indicates the status of
the path.
MODE=CONTROL The user requests control of the path.
(15) = 0 Operation begun.
-4 Too many devices attached.
-12 ORVYL-SUZAN path interface not available.
(0) = 32-bit path identifier
The path identifier is valid only when register 15 is 0.
(15) = 0 Attach completed. (Path identifier valid)
-8 No path device available. (Path identifier no longer
valid; path not attached.)
16 Other side of path not open. (Path identifier valid)
Note: The attention exit for a PATH device will be entered whenever any activity (partner close, new transaction, discretionary post, etc.) is noted.
READ id-l,location-la,length-la[,MODE=([WAIT][,TRUNCATE])]
(0) (1) (15)
Reads a message from a SUZAN path.
id-l path identifier
location-la Location of the area to receive the message
length-la 1st 16-bits: number of seconds to wait before
TIME-OUT (600 maximum) or zero
2nd 16-bits: length of the area. Maximum size
is 8192 bytes. 0 is invalid
MODE=WAIT The program will wait until the other side of the
path has been opened and a message is received.
If the timeout value is zero, the program will wait
indefinitely for a message to be received.
Otherwise, if the time interval expires before a
message is received, the return code in register 15
indicates the status of the path.
MODE=TRUNCATE If the message to be received is larger than the
specified area, the remainder will be ignored.
Note: if MODE=TRUNCATE is not specified, as much of
the message as will fit will be placed into the
area, and the remainder will be kept for subsequent
READ operations.
(15) = 0 Operation begun.
-12 ORVYL-SUZAN path interface not available.
(15) = 0 Successful completion.
-4 Other side of path has been closed. (Not MODE=CONTROL)
4 No messages received.
12 End-of-file message received. (MODE=CONTROL only)
16 Other side of path not yet open.
(1) = Number of bytes read. (register 15 = 0 only)
(14) = Number of bytes not read. (register 15 = 0 only)
Valid even for MODE=TRUNCATE
Note: Core storage in ORVYL is divided into pages of 4096 bytes each. A buffer area may not cross more than one page boundary. Thus, a buffer of 4096 bytes or less may begin on any byte; a buffer of 6144 bytes may begin as much as 2048 bytes from the beginning of a page; and an 8192-byte buffer must begin on a page boundary. For maximum efficiency buffers of 4096 bytes or less should reside on a single page.
WRITE id-l,location-la,length-la[,MODE=WAIT]
(0) (1) (15)
Writes a message across a SUZAN path.
id-l path identifier
location-la location of the area containing the message
length-la 1st 16-bits: number of seconds to wait before
TIME-OUT (600 maximum) or zero
2nd 16-bits: length of the area. Maximum size
is 8192 bytes. 0 is invalid
MODE=WAIT The program will wait until the other side of the
path is open and there is enough room for the
message in the other side's buffer. If the timeout
value specified is zero, the program will wait
indefinitely for the message to be sent. Otherwise
if the interval expires before the message can be
sent, the return code in register 15 indicates the
status of the path.
(15) = 0 Operation begun.
-12 ORVYL-SUZAN path interface not available.
(15) = 0 Successful completion.
-4 Other side of path has been closed.
8 Other side's buffer is full, message not sent.
16 Other side has not yet opened.
Note: Core storage in ORVYL is divided into pages of 4096 bytes each. A buffer area may not cross more than one page boundary. Thus, a buffer of 4096 bytes or less may begin on any byte; a buffer of 6144 bytes may begin as much as 2048 bytes from the beginning of a page; and an 8192-byte buffer must begin on a page boundary. For maximum efficiency buffers of 4096 bytes or less should reside on a single page.
COMMAND code-la,location-la,length-la[,MODE=(WYLBUR,NOCLP)]
(0) (1) (15)
Passes a command to the ORVYL Command Language Processor for execution. The MODE=WYLBUR option also allows passing of the command to WYLBUR or other subsystems for execution. The MODE=NOCLP option blocks command processing by the ORVYL Command Language Processor.
code-la 0 the command has been typed at the
terminal.
non-zero the command has not been typed at the
terminal.
location-la location of the area containing the command
length-la length of the area (maximum is 133)
(15) = 0 The command was executed.
4 An error was detected and a message has been typed.
If code-la was set as not typed, the command
was echoed as a part of the error diagnostic.
8 Command passed was the name of a subsystem. Control
was not passed to the subsystem. Use WRITE,MODE=EDIT
or COMMAND,MODE=WYLBUR to pass control to the
subsystem.
NOTE:
Since there are no means of reporting changes in the WYLBUR active file to the user program when using the COMMAND macro, WRITE,MODE=EDIT should be used whenever the program requires notification of changes to the active file.
EXIT
Returns control from a user program to the ORVYL Command Language Processor and clears the contents of user memory.
Does not return to the user program.
PAUSE
Initiates a Session Break. If, during the Session Break, the user enters a GO command, control will return to the instruction which immediately follows the PAUSE. Entering the ATTN command causes entry to the user's attention exit routine. The condition code and registers are preserved when the PAUSE macro is issued. All, however, may be changed by the user during the Session Break. In addition, the user may specify the address at which execution is to resume.
PANIC code-la
(0)
Used when an error condition is detected by a user program. PANIC causes a Session Break, unless a PANIC exit routine has been specified by the user.
code-la 15-bit code defined by the user program which
describes the error
No registers are changed, unless the user did so during the Session Break. The user may modify the address at which execution resumes.
A PANIC exit routine, if present, may cause resumption of main program execution at some point other than immediately after the PANIC macro call and may change register values.
SET code-la,location-la,length-la
(0) (1) (15)
Advises the supervisor of the areas of the program address space which
- will be needed soon.
- are no longer needed.
- not needed immediately, but still of use.
location-la location of an area of core storage
length-la length of the core storage area. For code 0
the maximum is 16K (16384), there is no limit
for codes 1 or 2.
code-la code = 0 The program intends to reference the
specified area soon.
1 The contents of the specified area are
no longer required by the program.
2 The program does not intend to reference
the specified area immediately.
NOTE: The supervisor manages storage in pages
of 4096 bytes each. If a page contains
any part of the area specified in the SET
macro, the request applies to the entire
page.
(15) = 0 Successful completion.
4 Unsuccessful due to insufficient pages. (code
0 only)
SET code-la[,interval-la]
(0) (1)
Sets the user's real or compute time interval timer. The timer is continuously decremented in either real or compute time. The user's timer exit routine is entered when the timer reads zero. The timer continues to decrement until reset.
code-la code = 3 real time interval
4 compute time interval
interval-la The time interval specified in units of 26 micro-
seconds, where a unit is equivalent to 1/38400
seconds. An internal specification of zero (0)
cancels any previously specified interval, if any.
(15) = Time remaining in the previous interval, if any.
SET code-la[,routine-la][,id-la][,user-info-la]
(0) (1) (15) (14)
Establishes the entry point of the specified exit routine.
code-la code = 5 set timer exit routine
6 set SVC exit routine
7 set PANIC exit routine
8 set ATTN exit routine for an I/O device
9 set WAIT exit routine for an I/O device
routine-la entry point of the routine or zero to disable exit
routine.
id-la the device identifier for codes 8 and 9.
NOTE: expressed as "la", not "l".
user-info-la any value specified by the program. Upon exit
routine entry, this value is placed in register
14. This parameter may be used to point to a
work area required by the exit routine.
(15) = Previous exit routine. (14) = Previous user information.
SET 10[,area-la]
(0) (1)
Issued by an exit routine, relinquishes control so that program execution may resume. Returns control to the point of interruption. The condition code, mask byte, and registers are preserved unless the user modifies the supervisor save area.
area-la Address of a modified save area image obtained using
a SENSE 15 macro within the exit routine. If none
is given, the supervisor area saved on entry to the
exit routine is used to resume execution of the
main code.
Execution resumes at location indicated by the PSW address contained in the specified area. See section 5.14.11 and 5.5 for more information.
SET 11[,mask-la]
(0) (1)
Sets the mask byte to enable or inhibit entry into exit routines.
mask-la mask byte, logical combination of:
X'80' = enable Timer exit
X'40' = enable ATTN exit
X'20' = enable WAIT exit
X'10' = enable PANIC exit
(15) = Previous mask byte.
SET 12,priority-la
(0) (1)
Specifies order-of-service priority.
priority-la priority from 0 to 15, higher numbers are
served first. Initial priority is 15.
(15) = previous priority
SET 13,disp-la,length-la,location-la
(0) (1) (15) (14)
Modifies the user or subprocessor communications area. This 16-byte area is separate from any user program space and may be used by the program in any manner. Each user program is assigned an individual communications area; each subprocessor maintains a single communications area for all users of that subprocessor.
disp-la Displacement of the first byte in the area to be
written. (Displacement from 0 through 15)
length-la number of bytes to be written.
location-la location of the data.
No registers changed.
SET 14,minlen-la,maxlen-la
(0) (1) (15)
Reserves memory for program work space.
minlen-la minimum additional amount of memory.
(i.e., that amount absolutely required
for the work space.)
maxlen-la amount of additional memory desired.
If maxlen=0, the maximum amount of memory
available to the program will be reserved.
(15) = 0 Successful completion.
4 Insufficient memory to satisfy request.
(1) = Initial address of additional reserved memory.
(0) = Amount of memory reserved.
SET 15,location-la,length-la
(0) (1) (15)
Releases memory from the program work space.
location-la location of memory to be released
length-la amount of memory to be released
NOTE: SET 15 manages storage in
pages of 4096 bytes each.
If a page contains any part
of the area described in the
SET macro, then the request
releases the entire page
from the program work space.
(15) = 0 Successful completion.
SET 16,location-la,length-la
(0) (1) (15)
Reserves memory for the program work space at a specific address within the limits of the work space (SEE the description of the SENSE 2 macro). An attempt to reserve pages not contained in the proper range or to reserve pages already reserved is a program error.
location-la location of memory to be reserved
length-la amount of memory to be reserved
(15) = 0 Successful completion.
4 Insufficient memory to satisfy request.
(1) = Location of memory reserved.
(0) = Amount of memory reserved.
SET 17,area-la
(0) (1)
Enables program event recording and allows specification of those events that cause an interruption. To disable program event recording, the programmer specifies a PER control block with a zero (0) event mask or a zero value in register 1.
area-la location of the 12-byte area that contains a new
PER control block (SEE Section 4.6 for a definition
of the PER control block.)
(15) = 0 Successful completion.
4 Request rejected; the user issued a SET EVENT
command at the terminal.
SET 18,area-la
(0) (1)
Enables monitoring and allows specification of the monitor mask. Monitoring may be disabled by specifying a zero (0) monitor mask or a zero value in register 1.
area-la location of a 4-byte area that contains the
monitor control block (SEE Section 4.6 for a
definition of the monitor control block.)
(15) = 0 Successful completion.
4 Request rejected; the user issued a SET MONITOR
command at the terminal.
SET 19,location-la,length-la
(0) (1) (15)
Precludes modification of the contents of a specified area in memory by the program or by input/output operations. The memory area to be specified must be reserved and defined.
location-la location of area to be protected
length-la amount of memory to be protected
(15) = 0 Successful completion
4 Page not defined
Note: The supervisor manages storage in pages of 4096 bytes each. If a page contains any part of the area specified in the SET macro, the request applies to the entire page. If any part of the area is not defined the protection operation is aborted without processing any succeeding pages.
SET 20,location-la,length-la
(0) (1) (15)
Cancels memory protection enabled by SET 19.
location-la location of protected memory
length-la amount of protected memory
(15) = 0 Successful completion
4 Page not defined
Note: The supervisor manages storage in pages of 4096 bytes each. If a page contains any part of the area specified in the SET macro, the request applies to the entire page. If any part of the area is not defined the protection operation is aborted without processing any succeeding pages.
SET 21,location-la,length-la[,MODE=TEST]
(0) (1) (15)
Provides a mechanism for obtaining exclusive control of a logical resource. No two programs may simultaneously use the same logical resource name. At the user's option, the program may be suspended until the required logical resource is available.
location-la Location of an area which contains a logical
resource name.
length-la Length of the name. Maximum is 128 bytes.
(15) = 0 Logical resource has been obtained for exclusive
use.
4 Logical resource not immediately available. (Only
occurs if MODE=TEST is specified.)
(1) = Reserved for future use.
Note: No specific format for resource names is defined or enforced. Cooperating users must define their own conventions. Only one logical resource at a time may be enqueued by each terminal.
SET 22,id-la
(0) (1)
Releases exclusive control over a previously enqueued resource.
id-la reserved for future use.
SET 23,value-la
(0) (1)
Sets the 1-byte value used to clear all newly defined virtual memory pages.
value-la value between 0 and 255
SET 24,location-la,length-la
(0) (1) (15)
Reset the program name to something other than the name of the program originally called.
location-la Location of an area which contains the new program
name.
length-la Length of the name, 1 to 8 bytes.
(15) = 0 Name has been changed.
SET 29,time-la
(0) (1)
Suspend program execution for specified short time interval, not to exceed 10 seconds. See STATUS 117 to suspend a program for a longer time.
time-la Count of 1/10 second intervals before
control is returned to the program.
(example: 100 = 10 seconds)
SET 30,symbol-la,length-la,location-la
(0) (1) (15) (14)
Define new shared symbol entry name and associated data area. Such symbols remain in effect until the shared program is reloaded. Typically, a shared program that makes use of SET 30 defines a lot of symbols and associated data areas. These are static tables of information that are of value to other programs, but are not directly linked into those programs. SENSE 30 of the symbol name will return the associated data area address, which is how programs access the static tables.
symbol-la Location of new symbol name to add to shared symbols.
length-la Length of symbol name, 1 to 255 bytes.
location-la Location of a data area to be associated with the new
shared symbol entry.
(15) = -4 Not allowed (program not authorized).
(15) = 0 New shared symbol entry has been defined.
(15) = 4 Already defined.
The SHOW VSYMBOLS command (or DUMP VSYMBOLS) will provide a complete list of the symbols, their associated data area value, count of users referencing them, and program name that defined them. A sample of SHOW VSYMBOLS follows:
Program Users Value Symbol
EMSDATA 128 0170439A S6EMS DISTRIBUTION
0170433A S6EMS NAME INDEX
01703828 S5ORV.GQ.EMS.DIRECTORY.<02>
01703778 S5ORV.GQ.EMS.DIRECTORY.<0B>
01702B08 S5ORV.GQ.EMS.DIRECTORY.<01>
01703FC0 S4ORV.GQ.EMS.DIRECTORY.<FF>
FOLDATA 4 0170DFC2 S6PFOLIO SYSTEM PROTO XEQ
0170DF72 S6PFOLIO PROTO XEQ
0170DF0A S6PFOLIO PROFILE READ
0170DE72 S6PFOLIO HELP READ
0170DBBA S6PFOLIO HELP HEADINGS
0170DB6A S6PFOLIO TABLES
0170CEE8 S5ORV.GG.SPI.PFOLIO.<0C>
0170CA30 S5ORV.GG.SPI.PFOLIO.<08>
0170BFB0 S5ORV.GG.SPI.PFOLIO.<04>
0170AE98 S5ORV.GG.SPI.PFOLIO.<03>
0170A1D8 S5ORV.GG.SPI.PFOLIO.<02>
01707B08 S5ORV.GG.SPI.PFOLIO.<01>
0170D278 S4ORV.GG.SPI.PFOLIO.<FF>
Note that unprintable characters are allowed in symbol names, but are shown in hexadecimal surrounded by brackets, such as <01>.
The following SET macros are reserved for systems programmers only. They can be used for the development of utilities or for testing system changes.
SET 150
(0)
Clears pseudo account (see STATUS 107).
(15) = 0 Done
SET 151,option-la
(0) (1)
Ignores multiple attentions.
option If F'1873' then set ignore multiple attentions
mode, otherwize clear ignore multiple attentions
mode.
(15) = 0 Done
SET 152,timer-la
(0) (1)
CLP only. See M1SERV and CLP code.
timer Timer value in TOD.
(15) = 0 Done
SET 153,timer-la
(0) (1)
CLP only. See M1SERV and CLP code.
timer Timer value in TOD.
(15) = 0 Done
SET 154,location-la,length-la,smfno-la
(0) (1) (15) (14)
Write an SMF record.
location Location of record length Length of record smfno SMF record number
(15) = 0 Done
~0 Error
SET 155,key-la
(0) (1)
Write an SMF record.
This function can be used to allow addressability to Orvyl global memory. It is recommended to use SENSE 153 unless it is necessary to have real time access to global memory.
key Program Key Mask
(15) = 0 Done
(1) Old key
WAIT 0
(0)
Allows a program to suspend execution while awaiting the expiration of a time interval, ATTN, or I/O completion.
Control is never passed to the instruction following WAIT 0. The user program should define the timer, ATTN, and/or WAIT exit routine(s) which are to receive control. The exit routine is responsible for altering the saved program address if execution is to resume at some other point. See sections 5.14.11, 5.13.8, and 5.5 for more information.
SENSE 0,location-la
(0) (1)
Reports on the status of the specified location in the program reserved address space.
location-la location to be tested
(15) = 0 The specified address is within the program reserved address
space and has been defined.
4 The specified address is within the program reserved address
space but has not been defined.
8 The specified address is not within the program reserved
address space.
(0) = Miscellaneous status information. (R15 = 0 only)
Bit:
0-29 Reserved.
30 Protected page.
31 Presently in core.
Note: The supervisor manages storage in pages of 4096 bytes each. Thus the status reported refers to the entire page in which the specified location resides.
SENSE 1
(0)
Obtains program work area management statistics.
(15) = Amount of memory available but not yet reserved for
program work area.
(1) = Total amount of memory available for program work area.
SENSE 2
(0)
Describes the memory address range from which program work area is reserved.
(15) = Length of the address space. (1) = Start of the address space.
SENSE 3
(0)
Reports today's date and the current clock time.
(15) = Year, month, and day in the format: YYYYMMDD.
(1) = Time of day in 26 micro-second units. This unit is
equivalent to 1/38400 seconds.
the terminal session in 26 micro-second units.
This unit is equivalent to 1/38400 seconds.
SENSE 4
(0)
Reports real and compute time since the beginning of the current terminal session.
(15) = Elapsed ORVYL compute time since the beginning of
the terminal session in 26 micro-second units.
This unit is equivalent to 1/38400 seconds.
(1) = Elapsed real time since the beginning of the
terminal session in 26 micro-second units. This
unit is equivalent to 1/38400 seconds.
SENSE 5
(0)
Reports the amount of time remaining in the current time interval as established by the user.
(15) = Time remaining in the current time interval. Time is
reported in 26 micro-second units, where a single
unit is equal to 1/38400 seconds.
SENSE 6
(0)
Detects the mask byte.
(15) = Mask byte, logical combination of:
X'80' = Timer exit enabled
X'40' = ATTN exit enabled
X'20' = WAIT exit enabled
x'10' = PANIC exit enabled
SENSE 7
(0)
Detects the service priority established for the program.
(15) = Priority (0-15).
SENSE 8,location-la
(0) (1)
Reports the current user, group, and terminal identifier.
location-la 27-byte area to receive data.
No registers changed.
AREA:
bytes 0-2: current user (uuu)
3: $
4-7: group and subgroup (ggrr)
8-10: terminal identifier (ann)
11-26: user session identification, if provided
SENSE code-la[,id-la]
(0) (1)
Reports the entry point of the specified exit routine location or completion status of a specific I/O device.
code-la code = 9 Timer exit
10 SVC exit
11 PANIC exit
12 ATTN exit for a specific device
13 WAIT exit for a specific device
14 Test for I/O completion on a specific
device.
id-la For codes 12, 13 and 14, the device identifier.
code = 9-13 (15) = Location of exit routine or zero if none
established.
(14) = User information specified when the exit
routine was established.
code = 14 (15) = 0 Operation completed on device.
4 Operation in progress on device.
SENSE 15,area-la
(0) (1)
Obtains the save area after a program interrupt. The exit routine can modify the copy of the save area received and use the modified copy to alter register contents or instruction execution sequence of main program when control is relinquished by a SET 10 macro. (See 5.13.8 and 5.5)
area-la Location of the 72-byte area which will contain
the program status word and general program
registers.
No registers changed
SENSE 16
(0)
Employed after an address PANIC, SENSE returns the address at which the PANIC exception occurred.
(15) = The PANIC exception address.
SENSE 17,disp-la,length-la,location-la
(0) (1) (15) (14)
Reads the 16-byte program (user or subprocessor) communications area.
disp-la Displacement of the first byte to be read (0-15).
length-la Number of bytes to be read.
location-la Location of the area which will receive the data.
No registers change.
SENSE 18,location-la,length-la
(0) (1) (15)
location-la Location of the area which will contain the
text.
length-la Length of the area. (If the specified area con-
tains less than 133 bytes, some data may be lost.)
(15) = 0 The command was typed.
4 The command was not typed.
(1) = Length of the command.
SENSE 19,location-la,length-la
(0) (1) (15)
Returns any parameter string specified with the command that initiated execution.
location-la location of the area which is to contain
the text.
length-la length of the area. (If the specified
area is less than 133 bytes, some data may
be lost.)
(15) = 0 Text was typed.
4 Text was not typed.
(1) = Length of the text string.
SENSE 21,location-la
(0) (1)
Obtains the 12-byte PER control block. If the PER event mask is zero (0), then PER is not enabled.
location-la location of the 12-byte area which is
to contain the PER control block
(15) = 0 PER not enabled or enabled by the user
program.
4 PER enabled with the SET EVENT command.
SENSE 22,location-la
(0) (1)
Obtains the monitor mask.
location-la location of the 4-byte area which is to
contain the monitor mask
(15) = 0 Monitoring not enabled or enabled by the user
program.
4 Monitoring enabled by the SET MONITOR command.
SENSE 23
(0)
Reports file system availability and space information.
(15) = 0 File system currently available.
4 File system unavailable.
(14) = Maximum allocation allowed any account.
(0) = File blocks available.
(1) = Total blocks in the file system.
SENSE 24
(0)
Senses the memory initialization value (SEE SET 23).
(15) = 1-byte value used to clear all new virtual
memory pages as they are defined.
SENSE 25
(0)
Reports ORVYL CPU time (see SENSE 4) and the ORVYL I/O count.
(0) = I/O count (1) = CPU time consumed under ORVYL in timer units. (14) = Elapsed time of session in timer units (15) = Virtual memory charge (page-seconds)
Note: A timer unit is equal to 1/38400 seconds (26 microseconds).
SENSE 26
(0)
Reports the time Block currently in effect.
(15) = 0 Successful completion
(1) = Time block
0 = Day
1 = Evening
2 = Night
3 = Weekend
SENSE 27,location-la,length-la,code-la
(0) (1) (15) (14)
location-la Location of the area which will receive the
HASP display buffer.
length-la Length of the area. (If the area is not long
enough, HASP data will be lost.)
code-la code indicating HASP buffer desired.
0 ENCINA status display
1 PINE HALL status display
(15) = 0 Successful completion.
4 Invalid option code.
8 HASP information truncated.
(1) = Length of data transferred.
SENSE 28,location-la
(0) (1)
location-la Location of 8 byte area to move the name too.
(15) = 0 Successful completion.
SENSE 29,location-la,length-la
(0) (1) (15)
symbol-la Location to receive the program name.
length-la Length of area. Program name could be truncated
if length specified is too short.
(15) = 0 Successful completion.
(1) = Length of program name.
SENSE 30,symbol-la,length-la
(0) (1) (15)
symbol-la Location of symbol name to find in shared symbols.
length-la Length of symbol name, 1 to 255 bytes.
(15) = 0 Successful completion, shared symbol name found.
4 Shared symbol name not found.
(14) = Data area address associated with shared symbol.
The following SENSE macros are reserved for systems programmers only. They can be used for the development of utilities or for testing system changes.
SENSE 151,location-la,length-la,fsid-la
(0) (1) (15) (14)
symbol-la Location to receive the file system info. length-la Length of area provided (at least 16 bytes). fsid-la File system id in hex
(15) = -4 Invalid file system id
0 Success, file system available
4 Success, file system not available mode
8 Success, file system in maintenance mode
(0) = 16, 28 or 36; length of data returned
bytes 0-7 File system name bytes 8-11 Count of blocks available bytes 12-15 Total count of blocks If area specified is 28 bytes or longer: bytes 16-19 F'1' if caching enabled, else F'0' bytes 20-23 Total disk I/O count bytes 24-27 Read count from cache (single) If area specified is 36 bytes or longer: bytes 24-31 Read count from cache (double) bytes 32-35 F'1' if 4K file system, else F'0'
SENSE 152,location-la
(0) (1)
This function moves the contents of the specified memory location in another address space to the specified location in this address space. It is documented for completeness but it is not apparent what practical use can be made of it since there seems to be no way to progmatically determine the first field of the sense 152 api. This function may have been developed to aid in testing or debugging durning some development phase of Orvyl.
symbol-la Location of sense 152 api
(15) = 0 Return code - completed
4 Function request failed
8 Address space channel busy
12 Failure in setting up requet
16 Request timed-out
20 Trouble posting AS
24 Requested AS not available
28 Function not implemented
SXASCPRM RECORD BEGIN
SXAASB DS A ASB of other AS
SXASLOC DS A Source address
SXADLOC DS A Destination address
SXADLEN DS A and length
SXATOD DS D Time for waiting (TOD fmt)
END ,
SENSE 153,location-la,length-la,address-la
(0) (1) (15) (14)
location-la Location to receive contents of global memory length-la Length of location address-la Global memory address
(15) = 0 Success
8 Invalid global memory address
SENSE 154,location-la,length-la,address-la
(0) (1) (15) (14)
location-la Location to receive contents of OS memory length-la Length of location address-la OS memory address
(15) = 0 Success
8 Invalid global memory address
UINIT resvm-l
(0)
Initialize URAM, set up memory management, attach master terminal, and other URAM housekeeping chores. This macro must be executed prior to the execution of all other URAM macros.
resvm-l Amount of core URAM will reserve for itself.
The remainder of core will be used by the user
program. URAM dynamically allocates ORVYL
memory pages. If the amount of memory is not
suffiecient URAM will attempt to allocate
more memory for itself.
(15) = amount of memory left for user to reserve (0) = length of memory until URAM memory (1) = start of memory
OPEN FCB-l,opnd-la
(1) (15)
Open the file or device. The parameters are merged into the FCB. An FCB is generated, if necessary. The device is attached and URAM initialization for the device takes place. Buffer allocation is done if appropriate. Assign command parameters override the parameters specified in the open parameter area. Default values are documented elsewhere.
FCB-l FCB address. This parameter is specified for
those devices for which an FCB has been
generated by an ASSIGN command.
opnd-la open parameter area. This area contains the
device parameters to be used in the open.
This area may be generated using the
OPNPARMS macro. The open parameter dsect
may be generated with the OPND macro.
(15) = error code (1) = FCB address
OPND
Copy the Open Parameter Dsect into the user program.
OPNPARMS NAME=,DEVICE=,IOTYPE=,
FILE=,FORMAT=,LENGTH=,VFORMAT=,VLENGTH=,
KEYED=,COMPRESSED=,LIBRARY=,MEMBER=,
DISP=,BLKSIZ=,VOLUME=,NOBUF=,
SRANGE=,ERANGE=,DELTA=,RANGE=,FCOL=,LCOL=,
PROMPT=,TIMEOUT=,PATH=,BUFFER=
Create an open parameter area with the parameters specified. Only the NAME= and DEVICE= parameters must be specified. The defaults are described in the Default section of this document.
NAME= File name to be associated with this FCB.
(Data set name)
DEVICE= Device type
ORV - ORVYL file
ACT - WYLBUR Active file
COMD - Command file
TERM - Terminal
NULL - Null file
BUFFER - Buffer I/O
SUZAN - suzan path
IOTYPE= Direction of I/O.
IN - input
OUT - output
INOUT - update
UPDATE - update
FILE= Name of ORVYL file to be opened.
FORMAT= Actual record format:
F - fixed length
VBS - variable length
E - edit (WYLBUR pressed format)
VT - variable text (WYLBUR format with
trailing blanks removed)
U - undefined
LENGTH= Actual record length
VFORMAT= Virtual record format:
F - fixed length
VBS - variable length
E - edit (WYLBUR pressed format)
VT - variable text (WYLBUR format with
trailing blanks removed)
U - undefined
VLENGTH= Virtual record length
DISP= Disposition of the file
NEW - create a new output file
OLD - read from an existing file
ERASE - erase existing file; write to new
file.
SHR - share
APPEND - append records to an existing
file
KEYED=YES Specified in addition to FORMAT=VBS for
INDEXED files.
COMPRESSED=YES File records in compressed form (valid for
format=vbs only)
MINBUF=YES Do not buffer I/O, this is a memory
conservation option. It minimizes the amount
of memory required by URAM to do I/O.
LIBRARY=YES ORVYL PDS library file
MEMBER= ORVYL PDS member name
SRANGE= Start of range
ERANGE= End of range
DELTA= Sequential increment factor
RANGE= This specification used if the range is associative
FCOL= first column of start of associative range
LCOL= last column of start of associative range
TIMEOUT= Time out for GETS (in seconds). Must be less
than 500.
VOLUME= <volume name>; volume on which data set
resides.
BLKSIZ= block size. valid for O.S. files only.
PROMPT= Address of prompt location formated:
2 bytes blank, 2 bytes length (n), n bytes prompt
PATH= 20 character suzan path identifier
USERBUF= Address of user specified buffer (BUFFER).
NOTE: OPERANDS ARE EITHER NUMBERS OR STRINGS NOT
ENCLOSED IN QUOTES.
CLOSE FCB-l
(1)
Closes specified file or device. If an output file, buffers are written. The buffers and FCB are freed. The device is detached.
FCB-l FCB address.
(15) = error code
GET buff-la,FCB-l,prompt-la,length-la[,MODE=PROMPT]
(0) (1) (15) (14)
Retrieves a record from the input file or device. The record number (key) may be specified for direct access devices. A prompt may be specified for terminal devices.
buff-la Buffer where record is to be placed,
if zero. A buffer will be supplied
and the address will be reurned in
R1. Another GET may overwrite this
buffer.
FCB-l FCB address.
recno-la Record number of the desired
record. If zero, file will be
treated as sequential.
prompt-la Prompt address. The prompt
location is formatted as follows:
2 bytes timeout information
2 bytes prompt length (n)
n bytes prompt text.
length-la Length of record to get. This
parameter is used only with
undefined gets.
MODE=PROMPT Specifies that R15 points to
a prompt area.
(15) = error code (1) = record address (0) = record length
PUT buff-la,FCB-l,recno-la,length-la
(0) (1) (15) (14)
A record is written to the output file or device. The record number (key) may be specified for direct access devices.
FCB-l FCB Address
buff-la location of record to be output
recno-la record number of record to be written
length-la Length of record to put. This
parameter is used only with
undefined gets.
(15) = error code
DELETE FCB-l,recno-la
(1) (15)
Delete a record from a URAM file. The record with the specified record number is deleted and its space freed. If the record does not exist, no operation is performed. This operation is valid for update or output files only.
FCB-l FCB-address
recno-la Record number of the record to be deleted
optional.
(15) = error code
GETPUTB FCB-l
(1)
This is a request for a buffer which will subsequently contain a record to be written out. The address is returned in register 1 and the length in register 0. GETPUTB may be interpreted as a priming call to the write routine, while PUT does the actual write. This buffer is reused so GETPUTB calls must be separated by PUT calls. However, a GETPUTB call is not required for each PUT, e.g., writing out a preformatted logical record would require only a PUT pointing to that record
FCB-l FCB Address
(15) = error code (1) = address of buffer (0) = length of buffer
ASSIGN strlen-la,,astring-la
(0) (15)
To generate an FCB from the text of an ASSIGN command. The ASSIGN command is documented (elsewhere). The parameters specified in the command text override those specified by the OPEN.
strlen-la Length of command text
astring-la Address of ASSIGN command text
(15) = error code (1) = FCB address
FCBD
Copy the File Control Block dsect into the user program. This dsect must be assembled into programs using the GET and PUT macros.
FUNC FINDFCB,FCB-l,FCB=CHAR
(0) (1)
Returns the address of the specified FCB.
FCB-l Pointer to 8 character string containing
FCB name.
FCB=CHAR FCB is specified as a character string.
Left justified and padded with blanks.
(15) = error code (1) = FCB address
FUNC FCBLIST
(0)
Obtain a list of existing file control blocks (FCB's). The list entries are 12 bytes long: 8 bytes FCB name, left justified, padded with blanks. 4 bytes FCB address. There may be empty (zeroed) entries in the FCB list.
(15) = error code (0) = number of entries in list (any entry may be zero) (1) = FCB list address
FUNC code
(0)
Turn on and off URAM printing of error messages
code operation code
Code Operation
---- ---------
ERROR cause URAM to print error
messages in addition to error
codes returned.
NOERROR suppress URAM error messages.
FUNC ERRORTEXT,FCB-l,errorcode-la,[MODE=URAM]
(0) (1) (15)
Return an appropriate error message text for the URAM error code specified in R15.
FCB-l address of FCB in which error occurred (if applicable)
errorcode-la URAM error code
MODE=URAM specifies that URAM will print error message
(15) = error code (0) = message length (1) = message text address
FUNC CLEAN,[FCB-l]
(0) (1)
FUNC CLEAN de-buffers files: Output buffers are written
out and input buffers are cleared. If a user plans to
modify his files directly with ORVYL macros. He may
use this macro to insure proper buffering. All files
or a specific file may be specified.
FCB-l denotes de-buffering of the specific FCB
(15) = error code
FUNC FREEPOOL
(0)
Close all files and return unneeded URAM system buffers.
(15) = error code
FUNC GETM,,length-la
(0) (15)
To obtain free storage for user program. Core is allocated in multiples of 4K. The user is responsible for further refinements in user memory management.
length-la amount of storage requested in bytes.
(15) = error codes (1) = address of start of storage obtained.
FUNC FREEM,length-la,address-la
(0) (15) (14)
Return previously obtained free storage to URAM.
length-la Length of storage to be returned.
address-la Address of the start of storage to be returned.
(15) = error codes
FUNC FIND,FCB-l,memb-la
(0) (1) (15)
Find a member in a ORVYL PDS file by member name. Succeeding GET's to the specified FCB will get records from that member. Used with the include libraries of PLC, WATORV, etc. Valid for input files only.
FCB-l FCB address
memb-la Address of the 8 character member name, left
justified and padded with blanks if necessary.
(15) = error code
FUNC DELMEMB,FCB-l,memb-la
(0) (1) (15)
Delete a member in a ORVYL PDS file
FCB-l FCB address
memb-la Address of the 8 character member name, left
justified and padded with blanks if necessary.
(15) = error code
FUNC REWIND,FCB-l
(0) (1)
Rewind a file.
FCB-l FCB address
(15) = error code
FUNC NOTE,FCB-l
(0) (1)
Returns in R1, the line or record number of the current record (input) or the next record (output). Line numbers are WYLBUR line numbers x 1000.
FCB-l FCB address
(15) = error code (1) = line or record number
FUNC POINT,FCB-l,dataline-la
(0) (1) (15)
FUNC POINT causes susequent file GET's to begin with the
line specified. The file must be an active file opened
for input.
FCB-l FCB address
dataline-la WYLBUR line number. (x 1000)
(15) = error code
FUNC code,,routine-la,userinfo-l
(0) (15) (14)
Establishes the entry point of the specified exit routine. These exit macros must be used in place of the ORVYL exit macros.
code operation code
Code Operation
---- ---------
ATTNEXIT set ATTN exit routine
SVCEXIT set SVC exit routine
routine-la entry point of the routine or zero to disable
the exit routine
userinfo-l any value specified by the program. Upon exit
routine entry, this value is placed in
register 14. This parameter may be used to
point to a work area required by the exit
routine.
(15) = error code (1) = previous exit routine (14) = previous user information
FUNC CMDEXIT,,routine-la,userinfo-la
(0) (15) (14)
Establishes an entry point in the user program. Command file commands are passed to this entry point. The command address will be passed in register R1; the command length in register R0. The exit routine address is pointed to by r14. If no entry is set, commands will be passed to ORVYL and WYLBUR.
routine-la command routine entry point.
userinfo-la any value specified by the user program
Upon exit routine entry, this value is
placed in register 15. This parameter
may be used to point to a work area
required by the exit routine.
(15) = error code (1) = previous exit routine (14) = previous user information
FUNC CMDRET
(0)
To return to URAM after user command file processing.
This chapter describes ORVYL maintenance commands that are generally restricted to system's programmers or special accounts. They are documented here for completeness, and are NOT intended for general users.
SET REFRESH shared-program-name
Used to refresh a shared program with another version. The refreshed version becomes a "corpse" which remains active until all users exit the program, or stop referencing symbols defined by the program. The new version isn't loaded until it is called, which should be done immediately for shared symbol programs.
Example:
SET REFRESH TSPIRES Shared program TSPIRES will be refreshed Ok?
SET VMAINT filesysname
Sets the file system into maintenance (read only) mode. This prevents changes to the file system by Orvyl while file dumps, lost block recovery, or other file system maintenace is occuring offline.
SET NOVMAIN filesysname
Sets the file system back to regular read/write mode.
SET NOVFILE filesysname
Sets the file system to unavailable mode. This prevents all access to the file system by Orvyl.
SET VFILE filesysname
Sets the file system back to regular read/write mode.
SHOW VVOLUME filesysname
Shows all the volumes that comprise the file system.
SHOW VVOLUME OOD
DSD Dataset name Start Count I/Os 0FAA40A0 WYL.GS.ORV.OOD.EMC.FILEX 0 317167 32702 0FAA4050 WYL.GS.ORV.OOD.EMC.FILE0 317167 317167 2241 0FAA4000 WYL.GS.ORV.OOD.EMC.FILE1 634334 317167 6385 08672E20 WYL.GS.ORV.OOD.EMC.FILE2 951501 317167 3068 08672DD0 WYL.GS.ORV.OOD.EMC.FILE3 1268668 317167 3864 08672D80 WYL.GS.ORV.OOD.EMC.FILE4 1585835 317167 935 08672D30 WYL.GS.ORV.OOD.EMC.FILE5 1903002 317167 1239 08672CE0 WYL.GS.ORV.OOD.EMC.FILE6 2220169 317167 1126 08672C90 WYL.GS.ORV.OOD.EMC.FILE7 2537336 317167 1296 08672C40 WYL.GS.ORV.OOD.EMC.FILE8 2854503 317167 1774
SET VADDVOL filesysname <dsn>
Adds another volume to the end of the file system. If the DSN of the volume is not specified, the next logical DSN will be derived from the current last DSN.
set vaddvol test3 Last WYL.GS.ORV.DFF.SYSD3.FILE3 Add WYL.GS.ORV.DFF.SYSD3.FILE4 to TEST3 ??? Ok? ok Volume added
SET VREMVOL filesysname <dsn>
Removes the last volume from the file system. The volume is validated to make sure that there are no blocks being used before it is removed.
set vremvol test3 Remove WYL.GS.ORV.DFF.SYSD3.FILE4 from TEST3 ??? Ok? ok Volume removed
FBAL account <reset>
This command adds up the blocks for each file belonging to the account and compares to blocks allocated for the account. It will report any discrepancies and additionally reset the blocks allocated if reset is specified.
Examples:
fbal gg.dff 1128 Blocks accounted, 1128 Blocks total in files for DFF$GG
fbal g2.dff 12 Blocks accounted, 8 Blocks total in files for DFF$G2 ** Error **
fbal g2.dff reset 12 Blocks accounted, 8 Blocks total in files for DFF$G2 ** Error ** Reset
CALL ADMIN USER ORV
This program performs various maintenance functions. It accepts the following commands:
DEFAULT ADD DROP RESET ACCOUNT ZORCH EXTEND CRENIXR CREHYBR
Enter EXIT when done.
DEFAULT <VERIFY|NOVERIFY> <BLOCKS nnn>
<TERMINAL|ACTIVE>
This command resets various defaults in the ADMIN program for use by some of the other commands.
VERIFY|NOVERIFY Specifies whether there is a response
from the ADD and DROP commands. The
program default is VERIFY.
BLOCKS nnn Specifies the default block limit for
the ADD and RESET commands. The program
default is 2500.
TERMINAL|ACTIVE Specifies whether the account command
puts the report in the active file or
lists it to the terminal. The
program default is ACTIVE.
ADD account <blocks|NOLIM>
This command adds an account to the Orvyl file system. The block limit is set to the default if blocks is not specified. NOLIM sets the block limit to 16777215. Note that there would not be a response in noverify mode.
Examples:
add gg.xxx 3500 GG.XXX ADDED WITH 3500 BLOCK LIMIT.
add gg.yyy GG.YYY ADDED WITH 2500 BLOCK LIMIT.
add gg.zzz nolim GG.ZZZ ADDED WITH NO BLOCK LIMIT.
DROP account
This command removes an account from the Orvyl file system.
Examples:
drop gg.xxx GG.XXX DROPPED FROM FILE SYSTEM.
drop g2.yyy G2.YYY: ACCOUNT STILL HAS FILES - NOT DROPPED.
RESET account <blocks|NOLIM>
This command resets the block limit to the default if blocks is not specified. NOLIM sets the block limit to 16777215. Note that there would not be a response in noverify mode.
Examples:
reset gg.xxx 3500 GG.XXX RESET TO 3500 BLOCKS.
reset gg.yyy GG.YYY RESET TO 2500 BLOCKS.
reset gg.zzz nolim GG.ZZZ RESET WITH NO BLOCK LIMIT.
ACCOUNT FSID n
This command lists all accounts and their block limits for the file system id specified. The file system id can be determined by issuing the SHOW VBLOCKS command and counting down to the desired file system starting with zero. The account list will go to the active file or the terminal depending on the ACTIVE|TERMINAL setting in effect.
ZORCH filename
This command removes a file catalog directory entry without releasing the blocks back to the sytem. The block allocation is not reset. The blocks are lost and must be reclaimed. The blocks allocated can be reset with the FBAL command if the account is not going to be dropped. The ERASE command should be used instead of ZORCH unless there is an overriding reason not to.
EXTEND filename nnn
This command extends a non-IXRd file by the count of blocks specified if possible. It reports the count possible if the count specified is not possible.
CRENIXR filename nnn
This command creates a non-IXRd file with the count of blocks specified if possible.
CREHYBR filename nnn
This command creates a hybrid file with the count of blocks specified if possible.
CALL PLAYMATE
PLAYMATE is an ORVYL utility program that permits the execution of commands in a form similar to ORVYL macros. The user has access to the full power of ORVYL on a command-by-command basis. The most frequent commands:
-? ATT FILE <filename> OLD -? READ BLOCK <number> -? DISPLAY BUFFER,<length> - - - - - etc. -? DETACH <R0-device>
PLAYMATE is typically used to examine SPIRES files.
-? ATT FILE myfile.MSTR OLD -? READ BLOCK 0 -? DISPLAY BUFFER
or
-? DISPLAY BUFFER,64 ; to limit the length.
ATTach FILe returns either an error code or it displays the registers that were returned by the operating system (ORVYL) when the file was successfully attached. R0 contains what is known as the device-id after a successful attach. Most commands, like CONTROL, READ, WRITE, DETACH, RESERVE, RELEASE need the file-di as their first parameter. READ BLOCK and WRITE PREV assume the current file-di. If you have more than one file attached at the same time, you'll have to specify the file-di on READ BLOCK or WRITE PREV if it wasn't the last file-di you used. You can READ BLOCK from one file, and WRITE PREV to another file.
All of these PLAYMATE commands are documented in the ORVYL manual, and PLAYMATE is an interactive way of executing the ORVYL macros. Just remember to use OLD on ATTach FILe when you are attaching an existing file. The default is NEW.
Here is another example using two files at once:
-? ATT FILE myold.file OLD -? ATT FILE mynew.file ; NEW is default -? READ BLOCK 0,2 -? WRITE PREV,3
Since device 2 is the first file attached, and device 3 is the second file attached, this set of commands reads block zero from myold.file and then writes it into mynew.file
PLAYMATE has a large number of commands:
1. ATTach FILe filename [,[MODE=] <modes>]
2. ATTach PATh pathname [,length]
3. ATTach <num> [r1-r14] [,[MODE=] <modes>]
4. SENse <num> [r1-r14]
5. STAtus <num> [r1-r14]
6. CONTrol [file-di] [r1-r14] [,[MODE=] <modes>]
7. REAd [file-di] [r1-r14] [,MODE=SKIp]
REAd BLOck <num> [,<di-num>] [,MODE=<modes>]
REAd NEXT [,<di-num>] [,MODE=<modes>]
8. WRIte [file-di] [r1-r14]
WRIte BLOck <num> [,<di-num>] [,MODE=<modes>]
WRIte PREV [,<di-num>] [,MODE=<modes>]
9. DETach [file-di]
10. REServe [file-di] [,[MODE=] <mode>]
11. RELease [file-di]
12. DISplay <area> [,<length>]
13. DISplay REGS
14. DISplay <regs> [, <regs>]
15. PRIme <area> [offset] "string"
PRIme <area> [offset] x'<hex-number>'
16. SVC <num> [r0] [r1-r14] [,[MODE=] <modes>]
17. MoVeCore <area> [offset] TO <area> [offset] LENgth[=]<num>
18. SORT [r0]
19. ETOA <area> [offset] [, <length>]
20. ATOE <area> [offset] [, <length>]
21. PAD <area> [offset] [, <length>]
Upper case portions of words are the minimum you can type to have that word recognized. Terms in angle-brackets, <term>, are required terms. Terms in square-brackets, [term], are optional. The commands make use of these definitions:
<modes> <mode> [, <mode>]
( <mode> [, <mode>] )
<mode> M14
M15 | OLD | SKIp
M0 | WAIt
M1 | SHR | SHAre | FORmat | TEXt
<regs> SVC | RETurn | WAIt | CALl
<area> BUFfer | STRing | CNTrl | PROmpt
<length> <num> | LBUFfer | LSTRing | LCNTrl | LPROmpt
<r1-r14> <r1> [r15-r14]
, <r15-r14>
<r15-r14> <r15> [r14]
, <r14>
<r0> , <value>
<r1> , <value>
<r15> , <value>
<r14> , <value>
<value> <area>
<length>
"string"
x'<hex-number>'
<offset> + <num>
<num> 0 <hex-number>
<decimal-number>
<di-num> <num>
<file-di> FILe
<num>
Alternatives are listed in a column under each definition, and horizontally separated by vertical-bar, |, when there are multiple choices for that one alternative. For example, <mode> can be M0 or WAIt for the M0 choice.
The last "string" or x'hex-number' will define the contents of the STRing area, and LSTRing will be the length of that string or hex-number (in bytes).
Both hex-number and decimal-number are what you'd expect.
PRIme <area> [offset] "string" PRIme <area> [offset] x'<hex-number>' PAD <area> [offset] [, <length>]
PRIME is used to place an initial value into an area. For example, you might need to setup a format for CONTROL 14 in the CNTRL area.
PRIME CNTRL X'04000040'
This would setup a FIXED,LRECL=64 format definition. You could then do the following to an attached file (device-id=2):
CONTROL 2,14,CNTRL,MODE=FORMAT
PAD is used to fill out an area by copying the last character in the current area until the area becomes <length> in size. Example:
PRIME BUFFER "Sample " PAD BUFFER,256 DISPLAY BUFFER 256 00000100 504000 0000 e2819497 93854040 |Sample | 504008 0008 to 00fc 40404040 | |
ETOA <area> [offset] [, <length>] ATOE <area> [offset] [, <length>]
These commands are used to convert the contents of an area from EBCIDIC to ASCII (ETOA) to ASCII to EBCIDIC (ATOE). This is usually done with the BUFFER area after reading a block of data from a file that has ASCII characters. PLAYMATE always displays as though the data was EBCIDIC, so you might have to do ATOE before doing DISPLAY.
Example:
READ BLOCK 0 ATOE BUFFER DISPLAY BUFFER
SORT [r0]
This command is used to sort the directory contents of an ORVYL Library or Loadfile. The Library or Loadfile must be an attached file.
This command reads block 0 of the specified file, [r0], sorts the contents, and rewrites the block. You will get errors if the attached file is not a Library or Loadfile, or you don't have read or write permission for the file.
Example:
ATTACH FILE PROGLIB OLD SORT
There are three batch programs that are commonly used to DUMP/RESTORE ORVYL files. ORVCOPY is used to dump/restore multiple files in their exact form. ORVMOVE and ORVLOAD are used to dump and restore respectively in a fixed format form.
ORVCOPY designed to DUMP/RESTORE ORVYL files.
Sample Output JCL
//SCR EXEC CATSCR,OPTION=IGNORE,DSN='WYL.gg.uuu.output' //step EXEC PGM=ORVCOPY //STEPLIB DD DSN=WYL.GG.PRD.ORVCOPY,DISP=SHR //SYSPRINT DD SYSOUT=A //OUTPUT DD DSN=WYL.gg.uuu.output,DISP=(NEW,CATLG), // UNIT=device,VOL=SER=volume,[SPACE or LABEL info] //SYSIN DD * DUMP control cards (to OUTPUT) /*
Sample Input JCL
//step EXEC PGM=ORVCOPY //STEPLIB DD DSN=WYL.GG.PRD.ORVCOPY,DISP=SHR //SYSPRINT DD SYSOUT=A //INPUT DD DSN=WYL.gg.uuu.input,DISP=SHR [assumes DSN is ON CAT] //SYSIN DD * RESTORE control cards (from INPUT) /*
SYSIN control cards
Control cards contain reserved words that may be abbreviated down to the first letter (like DUMP, DUM, DU, D). If the abbreviation would be ambiguous, then use at least the first three letter of the reserved word. REStore and REWind are examples of such words. SYSIN must be a fixed card image input data set, and only data in columns 1 through 72 is used. If the last non-blank character within that column range is a comma (,) then a second card is read as a continuation of the first.
There are three primary control cards:
a. REWIND b. [DUMP] options c. RESTORE options [REPLACE|SKIP]
REWIND positions the RESTORE (INPUT) data set to beginning of the data set.
DUMP is an optional keyword. RESTORE is a required keyword.
The "options" for both DUMP and RESTORE are:
a. ALL - process all files.
b. LIKE=stem - process all files with this stem.
c. RANGE=name1,name2 - process files such that:
name1 <= file <= name2
d. NAME=name [,RENAME=newname]
- processes a single file. The NAME is the
file read, and RENAME is the file written.
If RENAME is not given, NAME is written.
Note: DUMP's NAME is the ORVYL file name,
and RESTORE's NAME is the INPUT file name.
RENAME is allowed with both DUMP and RESTORE.
Do not include your account at the start of any name or stem. ORVCOPY knows your account from the JOB card; therefore, you may not dump files belonging to others, or restore to anyone but yourself.
The RESTORE control cards allow either REPLACE or SKIP as the last option. REPLACE is needed if the file being restored already exists under ORVYL and you want it to be replaced. If REPLACE is not given, only a new file can be restored. The SKIP option is very useful with the NAME option. SKIP positions INPUT to the named file but doesn't restore it. RESTORE ALL would then restore from that file through to the end of INPUT. SKIP with NAME makes it possible for you to position yourself to a particular file within INPUT's data set.
If a RESTORE command directly follows another RESTORE command, then LIKE, RANGE, and ALL read INPUT from its current position to end-of-information. The SKIP option causes the file names to be printed without restoring any of the files.
RESTORE with the REP option normally creates a standard ORVYL file, however if the file being restored already exists as a "non-ixr" or "hybrid" type, then the file is rewritten as that type.
Multiple ORVYL files are read/written from/to a single OS data set, which may be on disk or tape. The ORVYL file's attributes (FORMAT, CLP/NOCLP, SHR/NOSHR, FILEMASK, PUBLIC Permits, and Individual Permits) are all restored/saved by this program. As each file is processed, ORVCOPY prints a line in SYSPRINT that identifies the file written. The form of the line is:
** File=written.name
It is possible to DUMP and RESTORE in the same job step! However, INPUT and OUTPUT cannot specify the same data set.
Note that the RECFM for both INPUT and OUTPUT is: RECFM=VB. If you do not specify LRECL, or you specify an LRECL < 2056, then LRECL = 2056. Any specified LRECL >= 2056 is retained. If you do not specify BLKSIZE, or you specify BLKSIZE < LRECL+4, then BLKSIZE = 3(LRECL)+4. Any BLKSIZE >= LRECL+4 is retained. Therefore, default LRECL = 2056, and default BLKSIZE = 6172.
For dumping 4K file system files, you must supply LRECL=4104 as a minimum. BLKSIZE will be computed as 3(LRECL)+4 if not given. For restore of 4K files, LRECL and BLKSIZE are usually not given.
To route to other machines, include the following in the JCL:
/*ROUTE XEQ SYSx
To use a different ORVYL, like TESTORV, include the following:
/*JOBPARM ORVYL=TESTORV
ORVMOVE is designed to dump an ORVYL file to OS. ORVLOAD is the companion program, to load OS into ORVYL.
ORVMOVE Input: ORVYL file that is not a library or loadfile.
Types handled:
1. Unknown: Each block read equals one line of output.
Maximum size = 2048 or 4096
2. FIXED: LRECL determines size of each line output.
LRECL in your Output DD-card should match.
Maximum size = 2048 or 4096
3. VARIABLE: Text of each line equals one line of output.
Maximum size = 255.
4. EDIT: Uncompressed text equals one line of output.
Maximum size = 255.
Output: OS-dataset of either V(B) or F(B) record format. Each line of output from the ORVYL file equals one record in the OS-dataset. For F(B), records may be truncated or blank-padded to LRECL size.
You specify the name of the ORVYL file in either the PARM or //SYSIN. You specify the RECFM and LRECL of the output dataset in //OUTPUT.
ORVMOVE outputs statistics upon completion:
**File=<name-of-ORVYL-file> **** Blocks read: number of ORVYL file blocks input **** Lines output: number of lines written to //OUTPUT **** Lines padded: number of lines blank-padded (0 for VB) **** Truncated: number of truncated lines (0 for VB)
Sample JCL:
//SCR EXEC CATSCR,OPTION=IGNORE,DSN='WYL.gg.uuu.myfile.name' //GO EXEC PGM=ORVMOVE,PARM='myfile.name' //STEPLIB DD DSN=WYL.GG.PRD.ORVMOVE,DISP=SHR //SYSPRINT DD SYSOUT=A //OUTPUT DD DSN=WYL.gg.uuu.myfile.name,DISP=(NEW,CATLG), // UNIT=SYSDA,VOL=SER=SCR002, // SPACE=(2048,(269,10),RLSE), // DCB=(RECFM=FB,LRECL=64,BLKSIZE=2048)
The SPACE and DCB parameters should specify 4096 for files that have 4096 as their block size. Also, you should try to allocate the number-of-blocks associated with each file as the primary extent in the SPACE parameter.
Example:
Command> SHOW FILES LIKE myfile.name BLOCKS myfile.name -- 269 Blks (F: 0, L: 268)
See the SPACE parameter in the JCL above. Also note, SCR002 will normally take 24 ORVYL blocks (2K) per track.
ORVLOAD is designed to load an ORVYL file from OS. ORVMOVE is the companion program, to dump ORVYL to OS.
ORVLOAD Output: ORVYL file that is not a library or loadfile.
Types handled:
FIXED: Maximum size = BLKSIZE (2048 or 4096) LRECL of input determines LRECL of ORVYL output file.
Input: OS-dataset that must always be F(B) record format.
You specify the name of the ORVYL file in either the PARM or //SYSIN. You specify the RECFM and LRECL of the output dataset in //INPUT.
ORVLOAD outputs statistics upon completion:
**File=<name-of-ORVYL-file> **** Blocks moved: number of ORVYL file blocks output **** Record input: number of lines read from //INPUT
Sample JCL:
//GO EXEC PGM=ORVLOAD,PARM='myfile.name REP' //STEPLIB DD DSN=WYL.GG.PRD.ORVLOAD,DISP=SHR //SYSPRINT DD SYSOUT=A //INPUT DD DSN=WYL.gg.uuu.myfile.name,DISP=SHR
MPINIT -- Orvyl initialization parameters.
These are various parameters controling the various functioning of Orvyl.
SYSNAME is the name of this Orvyl. On SYSA and SYSD the name is set to ORVYL. On SYSB (RLIN) the name is set to ORVYLRLG. The default is TORVYL. The RESCAN parameter allows SYSNAME to be accessed more than once. Both the Host and the Guest access this parameter.
Example:
RESCAN SYSNAME = ORVYL
CPUS tells Orvyl how many CPUs will be used by the Guest.
Example:
CPUS = 3
This function still has to be researched. It is disabled in all known Orvyls.
Current setting:
BEGIN PROFILE ACTIVE = No ; Profiler inactive INTERVAL = 100 ; Profiler interval (ms) END PROFILE
This parameter tells Orvyl where the SYSM dump dataset is located.
Current settings on SYSA:
BEGIN SYSDUMP DSNAME = WYL.GS.ORV.SYSA.SYSM9000 ; Data set name VOLUME = DMPA02 ; Volume **Temporary** TRACKS = 12000 ; Secondary allocation GDG = +1 ; Its a gdg END SYSDUMP
Current settings on SYSA:
BEGIN SYSTEM GBLWSINT = 5000 ; Gbl work set interval (mS) SMFINT = 900 ; SMF interval (seconds) FRAMEINT = 10 ;was 20 ; Frame management (seconds) FRAMEINO = 3 ; num/cycle of frame mgmt END SYSTEM
These parameters are for the host.