McGill Systems Inc. September 19, 1996 Last updated: Oct 18, 2006 Enhancements to the Rexx MUSIO Command -------------------------------------- The previous Rexx MUSIO command (used to read and write MUSIC files from Rexx programs) had some deficiencies that often required the programmer to call function package routines MFACT/MFIO instead, needlessly complicating things. So we have made some additions to MUSIO. These additions are part of the March/97 Update to MUSIC/SP 5.1. The problems with MUSIO were: - When a new file was created, you couldn't control the space allocation, record format, record length, or access options. (This is solved by the new MIOGET/MIOSET routines.) - When an output file was closed, unused space at the end of the file was not freed, thus often wasting file space. (This is addressed by the CLOSERLSE option.) - It was not possible to create an empty file, since at least one record had to be written in order to open the file. (This is addressed by the WEOF option.) - In order to see if a file exists, or even to just check that a file name is valid, you had to read a record from it. (This is addressed by the EXTRACT option.) The additions to the MUSIO command are: (1) New Rexx function package routines MIOGET and MIOSET. These get and set the attribute values that Rexx uses when the MUSIO command creates a new file. The attributes are: primary space, secondary space allocation, logical record length, record format, and access control options. These are all passed to and from the routines by 5 integer arguments. The detailed calling sequences are given below. The current default values (if you don't call MIOSET) are: Primary space 8K, secondary allocation 150%, record format VC, access control = PRIVATE. Note: These routines are made possible by the "Rexx info area" that was added to $REX:REXX.S by MUSIC/SP 5.1. (2) New operation keywords on the MUSIO command, in addition to the existing READ, WRITE, APPEND, and CLOSE operations: 'MUSIO CLOSERLSE filename' Similar to normal CLOSE, but unused space is released. Note: If the CLOSERLSE fails (e.g. it's not your file and therfore you can't release the space), a nonzero RC is set and the file remains open. In that case you should do a normal CLOSE. 'MUSIO WEOF filename' Does a write-end-of-file operation. The file remains open, and the next operation should be CLOSE or CLOSERLSE. If no WRITEs precede the WEOF, the file is made empty (0 records). 'MUSIO EXTRACT filename' Does an extract operation on the file. This is similar to an open, but the file is not actually opened, and only the return code (RC) is set. EXTRACT can be used to test whether a file exists, or whether the file name is valid. For example, an invalid file name sets rc=12, a file that does not exist sets rc=30. Some General Notes ------------------ * Examples of usage of the MUSIO command are given in the MUSIC/SP User's Reference Guide manual, which is available on-line on MUSIC (type MAN) and in PDF form on the Web: see the Download page of the Sim390 web site. * On the MUSIO command, the keywords and file name must be in upper case. * Always check the return code (Rexx variable RC) after a MUSIO command, and take appropriate action. * If a MUSIO WRITE fails (nonzero RC), some or all of the queued records may be left in Rexx's stack. In most cases, you should remove all records from the stack after the WRITE, if RC is nonzero. The same for APPEND. For example: fn='*USR:MYFILE' /* file name */ queue 'record 1' /* add some records to the stack */ queue 'record 2' queue 'record 3' 'MUSIO WRITE' fn 'ALL' /* write records to file */ if rc/=0 then do /* test for error */ say ' Error' rc 'writing to file' fn do i=1 to queued() parse pull . /* remove record from stack */ end end * Do not try to use a blank or null file name with MUSIO. This can cause syntax problems with the command. For example, if fn='', the command 'MUSIO WRITE' fn 'ALL' is actually 'MUSIO WRITE ALL', which tries to write 1 record to the file ALL. * MUSIO WRITE, APPEND and WEOF commands use an existing file if there is one. The existing file may not have the desired size, record length, and record format. In that case you may want to call the PURGE routine to delete any existing file before doing the output. * When writing to a file (WRITE, APPEND, or WEOF), specify a specific directory or userid on the file name, as in \MYFILE (file in root directory of current userid) or .\MYFILE (file in the current directory). This prevents MUSIO from searching for the file in other directories or userids, and perhaps finding and using a file that you did not intend (e.g. a file in the common index). * Contrary to rumour, the MUSIO command is just as fast as the MFACT/MFIO routines (even a little faster, according to our tests). Also, MUSIO does not require the REXMFIO function package module (53K) to be loaded, and does not suffer from the complications of MFACT/MFIO (difficult arguments, obscure common blocks, etc.) MUSIO has its own complications (mainly to do with the Rexx stack), but overall is cleaner, and is a better solution if the complete control provided by MFACT/MFIO is not needed. Calling Sequence for MIOGET and MIOSET Routines ----------------------------------------------- (This is taken from the comments in source file $REX:REXX.MIOGET.S) call MIOGET 'PRIMSP','SECSP','LRECL','RECFM','ACCOPT' /* upon return, the variables contain the values currently in effect, i.e. those set by the last call to MIOSET, or the defaults if MIOSET was not called */ or: primsp=n /* set the values to be used by subsequent MUSIO commands when it creates new files */ /* ... */ call MIOSET 'PRIMSP','SECSP','LRECL','RECFM','ACCOPT' All arguments are integers. For MIOGET, they are all output. For MIOSET, they are all input. If MIOSET is not called, the initial values assembled into REXX.S at "NEWINF" are in effect. PRIMSP Primary space allocation, in K. This is the initial size of the file. SECSP Secondary space, in K. 0 means 50%. A negative value, -n, means n%. Secondary space is the amount to be added when the file must be expanded. A percent means that percent of the current size. LRECL Logical record length. May be 0 if not applicable (e.g. record format U, V, or VC). RECFM Record format: 0=U, 1=F, 2=FC, 3=V, 4=VC. Should be 4 (VC) in most cases, since that allows any size records (up to about 32000) and does automatic compression. ACCOPT Low order byte contains option bits for the 4-byte access control field for the file, as follows: x'01'=1 (SHR or RD) non-owners can read the file. x'02'=2 (WR) non-owners can write the file. x'04'=4 (AO) non-owners can write to the end of the file (append-only). x'08'=8 (XO) file is execute-only. x'10'=16 (COM) file is in the common index. x'20'=32 (CNT) file usage count is maintained. Examples: ACCOPT=17: file is public (readable and in the common index) (PUBL). ACCOPT=0: file is private (PRIV). ACCOPT=33: file is readable, not in the common index, and usage count is maintained. ACCOPT=24: file is exec-only and in common index.