.; VAL - VAL TERMINAL COMMUNICATIONS PACKAGE .page size 63 132 .left margin 15 .right margin 115 .figure 4 .center VAL PACKAGE .skip .center Document revision .center November 1981 .skip 4 .p The VAL package is a set of FORTRAN callable routines which facilitate terminal input and output. They provide a general purpose user orientated interface to the host operating system (RSX-11M in the current implementation). The purpose of VAL is four-fold: .skip .list .le To simplify terminal operations. .le To reduce programming effort. .le To standardise both the user interface and programming conventions .le To provide an interface to a command language system .end list .skip 3 .p The VAL routines were designed and implemented by Dave Plummer and Andrew Todd-Pokropek at University College Hospital London. Development was continued with the C.E.A. at Orsay France and at UCLA. .p This software is available to all non-profit making organizations on request and on the understanding that it will not be transmitted to another party for finantial gain. .p Feedback from users is realy important to a project of this size. Please send any: comments, modifications and bug reports to: .skip 2 .lm +16 .nofill Dave Plummer c/o Division of Biophysics Department of Radiology UCLA Center for the Health Sciences 405 Hilgard Avenue Los Angeles CA 90024, USA .fill .lm -16 .pg .title ###############VAL package guide .subtitle ###############Introduction .figure 3 .center INTRODUCTION .skip 3 .p Terminals represent a distinct class of peripherals which, though similar in many respects to other record orientated devices such as printers and record structured disk files, require significantly more sophisticated programming if they are to be used effictivly. .p Though program authors and other knowlegable 'computer people' are frequently content to use programs which give little prompt informaton and are totally unforgiving of typing errors, a large part of the computer using comunity now consists of those who have little computing experience. This is the case in many environments and notably in bio-medicine where clinicians, chemists, biologists etc. all need access to modelling, simulation and data processing systems. .p Conventional FORTRAN I/O provides no support for the current multiplicity of special terminal devices, offering line addressable displays, colour, protected fields etc. These facilities are readily supported by developing special software for individual applications, but this compromises the transportability of the resulting code which is then 'hard-wired' for a particular device type. .p It is easy to find fault with FORTRAN I/O syntax and propose improvements. However few people have either the time or the inclination to write new language systems. The most satisfactory approach to adding a more flexible I/O system to FORTRAN is to implement it as a set of subroutines and functions. This has two major advantages: .skip .list .le No modifications are required in the compiler or runtime system .le It is possible to produce a FORTRAN definition of the routines proposed, and so transport them easily (if not efficiently) between systems. .end list .skip The VAL package is a FORTRAN callable terminal I/O system implemented in this way. .skip .p Point 1 above is true for almost any implementation of VAL. Point 2 can be respected to a very large extent, but one system dependant feature has been found very useful and is widely exploited. The ability to determine, from a subroutine or function, the number of arguments passed in a call is an invaluable feature. Many intrinsic FORTRAN functions have variable numbers of arguments (MIN for example). Their use permits a single entry point to be given great flexibility and enables calls to use explicit or default values for parameters thus producing clearer and simpler programs. The PDP-11 implementation of FORTRAN provides this facility and the VAL package makes use of it. However no conceptual modification would be involved in decomposing the calls into separate entry-points with fixed numbers of arguments. .skip .tp 8 .p VAL provides the following basic features: .skip .list .le Free format input. Values are type converted as required and may be presented multiply on a line. Values are accepted in exponent form (ex. 1.65E3). .le Output formatting in a single statement. The combination of the format string with the argument list simplifies writing and reading programs. .le A default value may be specified in an input request and will be returned if the reply is CR or ';'. .le Range limits may be specified for any value requested. If the reply is out of range an error message is printed and the question is re-posed. If ? is replied to any question the details of the type and range of the item required will be printed. .le Replying to any question with CTRL-Z causes a user specified abort routine to be called. The programmer then has the choice of closing files and exiting, performing some special function or ignoring the interruption. .le The prompt is included in the input call. This permits a question to be interrupted (by a range error for example) and the question to be re-posed on return. .le Input and output calls may be easily issued from assembly code programs and routines. .le All input and output is under user control. It is thus simple to interface to some form of command language and provide extensive task control features. The current implementation supports the CLONE command language. The special characters @ and ESCAPE invoke the CLONE processor. See the CLONE users guide for further details of the CLONE system. .end list .skip 2 .pg .subtitle ###############Using VAL routines .figure 3 .center USING THE VAL ROUTINES .skip 3 .p All the routines described below may be linked from the library: .skip .i +16 LB:[1,1]UTYLIB .skip If a FORTRAN or FCS resident library is used no additional action is required. However if not, a window block must be explicitly allocated, for the mapping of VAL communications regions, by including the statement: .skip .i +16 WNDWS=1 .skip in the TKB options input. .p The routine START must be called before any other VAL routine. It is generaly recomended that START be called as the first executable statement of every program. FINISH should always be called to terminate program execution as a direct call to EXIT (or STOP) may leave other programs in an undefined state. .p Though it is possible to mix VAL input calls with standard FORTRAN input this will genarally be confusing for the user, as input conventions will be different and type-ahead will not work as expected. .p The functions DIRVAL and STRVAL described below return integer results though in FORTRAN their names give them the type REAL. If these function calls are used they must be explicitly declared as type INTEGER. .skip .i +16 INTEGER DIRVAL,STRVAL .pg .subtitle ###############Task control routines .figure 3 .center TASK CONTROL ROUTINES .skip 3 .p The routines described in this section provide for system initialization and inter-task communication. START and FINISH are called by all VAL programs. GOTASK and CHAIN are used to enable one program to start another. .skip 3 .tp 10 START and FINISH .p The routine START is called to initialize the VAL system. It should genarally be the first executable statement of a program. START performs the following functions: .skip .list .le An attempt is made to receive a message from another task. Such a message would be sent by the GOTASK or CHAIN calls described below, or by CLONE when a RUN command is executed. If the attempt succedes, the task receives a referance to a dynamically created region of memory which contains current information for the program. If the receive fails, START creates and initializes a dynamic region. .le A Logical Unit Number (LUN) is assigned to the terminal to be used by VAL for communication. Normaly this terminal will be the TI: of the program, but in certain cases an explicit terminal independant of TI: may be used. .le Finally, if the call to START specifies a user buffer to receive information, a 16 word data block will be copied from the dynamic region to this buffer. The format of this block is: .list .le Two words containing the name of the task which requested the present task via CHAIN or GOTASK. If the task was RUN directly these two words will both contain -1. .le Two words containing the name of the task to which the present task will return on a call to FINISH. If called via GOTASK this will be the same as the first two words, if called from another task via CHAIN it will be the return task name for that task, and if not called by another task it will be -1. .le The unit number of the TI: terminal .le a global event flag number which is reserved for use by this TI: .le Ten words transmitted as data in the GOTASK or CHAIN calls. This buffer will be zero if no data was sent. .end list .end list .skip .tp 12 calling format: .skip .i +16 CALL START[IDATA,LUN,DEV,UNIT)] .skip .lm +16 .i -16 where:##IDATA###is the 16 word user buffer as described above. If this argument is omitted no data is copied. .i -8 LUN#####is the FORTRAN LUN to be assigned to the terminal device. The default for this parameter is 6. .i -8 DEV#####the name of the terminal device to be assigned to LUN. The default for this parameter is 'TI'. A value of zero will cause the device assigned by TKB to the LUN to be used. .i -8 UNIT - #is the unit number of the terminal device to be used. Default 0. .skip 2 .lm -16 ex. .br .i +16 CALL START(BUF,5,'TT',1) .skip any or all arguments may be omitted. .skip 6 .tp 10 FINISH and DISCON .p FINISH performs VAL termination operations and then transfers control to the FORTRAN routine EXIT. If the task was requested via GOTASK from another program, FINISH will cause the calling program to continue from the call. .p DISCON also terminates VAL operations and resumes any caller task, but this call returns and the program may continue doing any processing which does not use VAL calls. A VAL call after DISCON will generate a fatal error. .tp 6 .skip calling format: .skip .lm +16 CALL FINISH[(IDATA)] .br CALL DISCON[(IDATA)] .lm -16 .skip .lm +16 .i -16 where:##IDATA###is an optional data buffer as described under START. Note that the first 6 words of this buffer will be ignored as the internal VAL parameters cannot be modified. .lm -16 .pg GOTASK and CHAIN .p These two routines facilitate transfer of control between tasks. They are specifically intended for use in 'packages' comprising several tasks which are requested from each other or from a 'root' task. Use of these routines renders the task-to-task transitions quite invisible to the user as the current type-ahead buffer and VAL parameters are transmitted between tasks. GOTASK starts the new task and waits for its completion before returning whereas CHAIN starts the new task and exits. .skip .tp 16 calling format: .skip .lm +16 CALL GOTASK(NAME[,IDATA,IERR]) .br CALL CHAIN(NAME[,IDATA,IERR]) .skip .lm -16 .lm +16 .i -16 where:##NAME#### is the RAD50 name of the task to be requested. .i -8 IDATA###is the communications buffer as described for START. If this argument is specified in a GOTASK call its contents will be passed to the new task and the FINISH parameters will be returned on completion. The user must thus be aware that the contents of this buffer will be modified. .i -8 IERR####Receives a success or error status for the call. If on return the value is negative, the task was not requested and the value will be the RSX error code. If positive the value is the status with which the called task exited. This will be one for normal completion, two for an abnormal termination and three for a severe error. .lm -16 .pg .subtitle ###############Terminal input routines .figure 3 .center TERMINAL INPUT ROUTINES .skip 3 .p The terminal input routines provide the programmer and the user with the maximum of flexibility for the minimum of effort. For the programmer these routines provide: prompting, defaults and range checking and help in a single call. For the user they provide: free format input, some protection from typing errors, and an interface to help and command language utilities. .skip 3 Input conventions .p It is intended that by providing a uniform interface to programs via the VAL package, users will require less instruction in their use as experience will be genarally applicable. The following conventions will apply to all input requests. .skip 3 Numeric input .p Values are requested by the program as either integers or reals. However the values typed by the user may be in any format and will be converted by the input routine. Integers will be floated to reals and reals will be truncated to integers. Numeric values may be entered in any of the following formats: .skip .lm +8 352######### a simple integer number .skip 3.14159##### a real number .skip 1E3######### an integer expressed in scientific notation .skip 5.6E-5###### a real expressed in scientific notation. .skip .lm -8 .skip All of the above would be possible replies to either an integer or real input request. A restriction in the current implementation is that each field is evaluated as a 16 bit integer and thus has a maximum absolute value of 32767. Thus the following real numbers are invalid and must be entered using scientific notation or with less precision. .skip .nofill .lm +16 INVALID VALID .skip 500000 5E5 32.1234567 32.12345 .lm -16 .skip .fill .p Any number of values may be placed on a line, they will be buffered internally and used for the individual input calls as they are issued. Multiple replies may be seperated by spaces or commas. When the answer to a question is already in the input buffer then prompt text supplied in the input call is not printed. .p Numeric input requests may specify a default value. If the reply to a question is carriage return the default value is returned to the program. A carriage return may be simulated within a line of multiple replies by the character ';'. .p Numeric input requests may specify range limits. The reply is then required to fall within this range. If this is not the case: an error message is printed, the type ahead buffer is cleared and the question is re-asked. In addition, if the program is running under the CLONE command language, the question is forced to the terminal to avoid the macro loosing syncronization. .p The input request type, the default value and the range limits may be obtained by typing ? to any question. This causes the values to be printed and the question to be re-asked. .skip 3 Directory lookups .p A special type of numeric input request in the directory lookup. This is intended for use in options lists where the options are to be given names. The input call includes a table of name-value pairs. The user may then reply either the numeric value or the name, but in either case the result is the numeric value. .skip 3 String input .p There are two main types of text string: .skip .list .le Strings read to end of line containing any characters. These are used for ID text etc. .le Strings read to some seperator such as space. These are normally file names or similar items which have a tightly defined syntax. .end list .skip 5 FORMAT OF INPUT CALLS .p The numeric input calls exist in two forms: as function calls and as subroutine calls. The distinction is largely historical except that the subroutine input calls, as they pass the result location as an argument, permit an additional type of reply being '/' which means 'leave the current value unchanged'. .skip .tp 10 The input calls are: .skip .lm +5 .nofill function subroutine .skip INTVAL VALINT input an integer value REAVAL VALREA input a real value DIRVAL VALDIR input an integer value with directory lookup STRVAL VALSTR input a string value (function result is length) PRSVAL parse a string to one of a specified set of seperators .skip .lm -5 .skip 3 The NAME argument .p The input functions have a uniform argument format. In every case the first argument is a string value being the name of the value being input. This may be the actual FORTRAN variable name but can be any name string of up to six characters. Frequently this argument is left null. However if it is supplied it provides a mechanism for uniquely identifying the request for a particular value, even when it is requested from different points in the code. This permits a HELP utility to be implemented which provides help given the request name and the name of the program. This name is also passed to CLONE and may be used to referance the CLONE symbol table directly without the need for an explictit reply in the macro. This is a useful mechanism for fixing values which are to be asked many times, and avoiding questions which are asked conditionally on some condition which is inaccessible to a macro. .pg INTVAL, VALINT - input an integer value .skip calling format: .skip .lm +16 I=INTVAL(NAME,PROMPT,IDEF,MIN,MAX) .br CALL VALINT(IRES,IDEF,MIN,MAX) .lm -16 .skip .lm +16 .i -16 where:##NAME - #Is a zero terminated string of up to 6 characters assigning a name to this input request. This name may be used by help and command language systems to uniquely identify the request. (see notes above on the name parameter) (INTVAL only) .i -8 PROMPT-#is a zero terminated string of up to 80 characters to be used as the question prompt. The string is printed is supplied and with no trailing carriage control (as with $ FORMAT) so that the reply appears on the same line as the question. (INTVAL only) .i -8 IRES####is the integer variable to receive the result of the input request (VALINT only) .i -8 IDEF####is an integer value to be used as the default for the input request if the reply is RETURN or ';'. .i -8 MIN#####is the low range limit. If the reply to the question is less than this limit an error message will be produced, and the question will be asked again. .i -8 MAX#####is the high range limit. If the reply to the question is greater than this limit an error message will be produced and the question will be asked again. .skip .lm -16 Any or all of the arguments may be omitted in the INTVAL call but if range limits are supplied they must both be present. .skip The VALINT call does not take the name and prompt arguments. These may be supplied with a prior call to VPRMPT described below. In this call the IRES argument is required but the other arguments may be omitted as for INTVAL. .skip 6 .tp 10 REAVAL, VALREA - input a real value .skip calling format: .skip .lm +16 I=REAVAL(NAME,PROMPT,RDEF,RMIN,RMAX) .br CALL VALREA(RES,RDEF,RMIN,RMAX) .lm -16 .skip .lm +16 .i -16 where:##NAME####Is a zero terminated string of up to 6 characters assigning a name to this input request. This name may be used by help and command language systems to uniquely identify the request. (see notes above on the name parameter) (REAVAL only) .i -8 PROMPT##is a zero terminated string of up to 80 characters to be used as the question prompt. The string is printed is supplied and with no trailing carriage control (as with $ FORMAT) so that the reply appears on the same line as the question. (REAVAL only) .i -8 RES#####is the real variable to receive the result of the input request (VALREA only). .i -8 DEF#####is an real value to be used as the default for the input request if the reply is RETURN or ';'. .i -8 RMIN####is the low range limit. If the reply to the question is less than this limit an error message will be produced, and the question will be asked again. .i -8 RMAX####is the high range limit. If the reply to the question is greater than this limit an error message will be produced and the question will be asked again. .skip .lm -16 Any or all of the arguments may be omitted in the REAVAL call but if range limits are supplied they must both be present. .skip The VALREA call does not take the name and prompt arguments. These may be supplied with a prior call to VPRMPT described below. In this call the IRES argument is required but the other arguments may be omitted as for REAVAL. .skip 6 .tp 10 DIRVAL, VALDIR - lookup a value in a directory .skip calling format: .skip .lm +16 I=DIRVAL(NAME,PROMPT,DIR,IDEF,MIN,MAX) .br CALL VALDIR(IRES,DIR,IDEF,MIN,MAX) .lm -16 .skip Arguments and conventions are as for INTVAL except for the argument DIR. This argument is a byte (LOGICAL*1) array of text values and their associated integer values. As the integers are stored as 8 bit signed numbers they must fall in the range -128 to 127. However direct numeric replies to the call may use the full integer range. The directory format is as follows: .skip .nofill .lm +10 0 .skip up to 6 characters of name matching code: 0 accept unambiguous match to end of input string. -1 accept only identical match. associated value .skip (the name, code and value are repeated for as many names as are required.) .skip 0 0 .lm -10 .fill .skip For example suppose valid responses to an input request were to be: any positive value greater than zero, 'NONE' or 'ALL'. And 'N' is to be a sufficient reply to signify 'NONE' but 'ALL' is required in full. Let 'NONE' be associated with the value -1 and 'ALL' with the value -2. The directory would then be created in FORTRAN by: .skip .nofill .lm +6 BYTE DIR(14) DATA DIR/0,'N','O','N','E',0,-1,'A','L','L',-1,-2,0,0/ .skip 2 .fill .lm -6 Note that if an exact match is not required, a string longer than the directory entry will be accepted. Thus sufficient characters need only be included in DIR to make the lookup unambiguous. If a reply is given which does not match any of the directory entries or which cannot be resolved unambiguously the result will be zero. .skip 6 .tp 10 .skip 6 .tp 10 STRVAL, VALSTR - input a text string to end of line .skip calling format: .skip .lm +16 L=STRVAL(NAME,PROMPT,STR,LEN,L) .br CALL VALSTR(STR,LEN,L) .lm -16 .skip .lm +16 .i -16 where:##NAME and PROMPT are as above .i -8 STR#####is a buffer to receive the text string read. .i -8 LEN#####is the length of STR. characters beyond this length are left in the input buffer .i -8 L#######receives the actual number of characters read. .lm -16 .skip In both calls STR and LEN are required arguments. .skip 6 .tp 10 PRSVAL - parse a string input .p This routine parses string items from the current VAL buffer and requests input if the buffer is empty. It is intended for inputting file names and similar items which may contain VAL seperators. .skip .i +16 CALL PRSVAL(NAME,PROMPT,BUF,LEN[,L,SEPSTR,ITERM]) .skip .lm +16 .i -16 where:##NAME and PROMPT have their usual VAL interpretations .i -8 LEN#####is the length of BUF .i -8 L#######receives the number of characters returned .i -8 SEPSTR-#seperator list as described below. This should be a zero terminated string. .i -8 ITERM###integer location which receives the ascii code of the terminating character. .skip .lm -16 The string parsed is placed in BUF and zero terminated, if L is specified it receives the number of characters placed in BUF. As a zero byte is always returned BUF should be one byte longer than the longest string expected to be read. If LEN characters are found before a terminator is reached the remainder of the input will be disgarded. .skip parsing rules: .list .le Leading blanks and tabs are always disgarded. .le The first non-blank character and subsequent characters are copied to BUF until a seperator is encountered. .le Default seperators are space, comma and end-of-line. An alternative seperator list may be specified as the argument SEPSTR. This argument should be a zero terminated string of those characters which are to be considered as terminators. However end-of line always terminates the string. .le If the first non-blank character is ' or " the string is copied up to a matching quote or end-of-line whichever is encountered first. The enclosing quotes are disgarded. .le Within a string, text enclosed in parentheses () [] {} or quotes '' "" is not scanned for terminators. .end list .skip 6 .tp 10 VPRMPT and VINPUT - line by line input routine .p These two routines are called by the above input routines to prompt and perform input. They may also be called directly if only line-by-line input is required as when some special parsing is being employed. Using only these two routines for input will also save a significant ammount of memory over the full VAL parser. Also when the VALxxx subroutines are used, VPRMPT is the only means of generating a prompt message. .skip 2 calling format: .skip .lm +16 CALL VPRMPT(NAME,PROMPT) .br CALL VINPUT(BUF,LEN,L) .lm -16 .skip The NAME and PROMPT arguments are as above. The VINPUT call requires all three arguments. BUF is the buffer to receive the line read. LEN is the length of BUF and L receives the actual length of the line. The buffer is not zero terminated or blank filled. If the reply to a question is CTRL-Z this will appear in the buffer as its ASCII code. .pg .subtitle ###############OUTS output routines .figure 3 .center OUTS .skip 3 .p OUTS provides a set of FORTRAN or MACRO callable routines for the output of text and numbers to terminals and printers. OUTS enables output requests to be expressed in a simple form which avoids separate format statements without restricting generality. OUTS provides support for devices which require special parameters such as colour tv and cursor addressable terminals. It can be readily extended to accomodate any special device in a compatible manner. .skip 2 the basic call is:- .skip .i +16 CALL OUTS('TEXT'[,V1,V2...]) .skip .lm +16 .i -16 where:##TEXT####is any string which may contain the the special symbols _# and _& to indicate the positioning and format of substituted values and text. .skip _# signifies a decimal digit .br _& an ascii character .br _. indicates the position of a decimal point within a real number .skip These special characters are replaced by values taken from the argument list following the text. .skip .lm -16 thus the following call: .skip .lm +16 .nofill I=3 B=55.6 CALL OUTS('FIRST IS _#_# SECOND IS _#_#_#_#._#_#_#',I,B) .skip .fill .i -8 produces the output: .skip FIRST#IS##3#SECOND#IS###55.600 .skip .i -8 on the terminal. .skip .lm -16 character strings may also be output by: .skip .lm +16 .nofill DATA STR/'STRING'/ .... I=66 CALL OUTS('_&_&_&_&_&_& _#_#',STR,I) .skip .fill .lm -16 When real values are output the decimal point must be preceded by at least one _#. .skip 3 .tp 10 .p A similar call is OUT. This has exactly the same syntax as OUTS but does not output any text immediatly. Repeated calls to OUT produce text concatenated in a buffer which will only be output when OUTS is called. Thus: .skip .lm +16 .nofill CALL OUT('I=_#_#_#',I) CALL OUT(' J=_#_#_#',J) CALL OUTS(' V=_#_#_#._#_#_#',V) .skip might print: .skip I=#16#J=##3#V=125.145 .skip .fill .lm -16 which is only output when the last call is issued. .p The maximum length of line which may be composed in this way is currently 80 characters. .skip 3 .tp 10 .p OUTS may be passed additional parameters after the value list. These may be used for output device selection and for special formatting commands such as selecting a line on a vdu screen. These parameters will be somewhat implementation dependant as different hardware configurations will have different requirements. However by convention the first will be called 'LINE' and will describe the output position and the second will be 'IDEV' and will describe the output device. .skip The general call is thus: .skip .i +16 CALL OUTS('TEXT',V1,V2....,LINE,IDEV) .skip Any arguments may be omitted except that if a format character exists within TEXT the corresponding value must also be present. If TEXT is omitted, a line is output either null or containing any data previously stored by OUT. If LINE is omitted the current default line stored within OUTS is used. If IDEV is omitted the current default device is used. This will generally be the terminal on which the calling program is running. .skip 3 .tp 10 Interpretation of LINE .p The LINE parameter may be used to select individual lines or character positions on the screen. In the basic implementation only the following value are used: .lm +8 .skip 0 output a form feed before output .br 1 write to top line of screen ( if this function is supported) .br 2 write in prompt mode (as with $ FORMAT) .skip .lm -8 .skip 3 .tp 10 Interpretation of IDEV .p Values of less than 65. are interpreted as indices in an internal device name table 'devtab' which yields a name and unit for the specified device. The following codes are recognized by the basic implementation. .skip .lm +8 #0 write to TI: the terminal on which the task is running. .br -1 write to NL: the 'black hole' device. This works even on systems with no NL: .skip .lm -8 .p If IDEV is greater than or equal to 65. it is interpreted as a device name string ex. .skip .i +16 CALL OUTS(MESSAGE,,'TT3:') .skip .skip 3 .tp 10 OUTSAV - modify default values .p The default values of these parameters may be modified with a call to OUTSAV. .skip .i +16 CALL OUTSAV(LINE,IDEV,LUN,MAXLIN) .skip .lm +16 .i -16 where:##LINE####sets the default for the line parameter as described above .i -8 IDEV####sets the default for the IDEV parameter described above. .i -8 LUN#####sets the logical unit number to be used for output .i -8 MAXLIN-#sets the number of lines on the screen .skip .lm -16 .skip Any of these arguments may be omitted to leave the current value unchanged. .skip 3 .tp 10 OUTTAB - 'tab' to a specifed column .skip .i +16 CALL OUTTAB(ICOL) .skip This sets the internal character pointer to the specified column number. The specified column may be before or after the last character written and text previously stored is not affected. After a call to this routine the next text written with OUTS or OUT will start at the specified position in the line. Note that if the pointer is moved backwards the internal buffer is overwritten rather than overprinting on the terminal. .p OUTTAB may also be called as an integer function with no arguments to read the current character position. .skip 3 .tp 10 OUTCLR - reset the buffer pointer and clear buffer .skip .i +16 CALL OUTCLR .skip This routine erases any text currently placed in the buffer and not output. It may be useful to clear the buffer after an error while composing a buffer with OUT. OUTCLR has the same effect as a write to the null device NL:. .skip 3 .tp 10 OUTLUN - select a different LUN for output .p The lun used for output is 5 by default but may be changed by a call to OUTSAV. This LUN is assigned to the selected device before each output call. This may be undesirable in some circumstances for example if the device is attached. In this case the call: .skip .i +16 CALL OUTLUN(LUN) .skip can be used to specify a new lun for output which will not be assigned automatically by OUTS. This routine should be called with an argument of zero to return to the default LUN. .pg .subtitle ###############Additional VAL routines .figure 3 .center ADDITIONAL VAL ROUTINES .skip 3 VALERR - Notify VAL of an error condition. .skip This routine permits the user to notify the system that some exceptional error condition has taken place. Further input takes place in special-mode. This mode has no effect when the program is not under CLONE control. However when it is, all requests are forced to the console so as not to lose syncronization with the normal flow of CLONE replies. When a range error occures on an input request the next request automatically takes place in special mode. The purpose of this routine is to enable the same mechanism to be used for errors detected by the program, such as file open fails etc. .skip .i +16 CALL VALERR([N]) .skip .lm +16 .i -8 if N=0##or absent the input buffer is cleared and the next request takes place in special mode. .i-8 if N>0##The input buffer is cleared and VAL latches in special mode .i -8 if N<0##VAL exits from special mode. This clears an internal flag and calls the internal routine CLRERR. .skip .lm -16 .skip 6 .tp 10 VALTST - test for immediate availability of input .p This routine may be used to determine if an additional prompt message need be output. If a prompt is too long or complex to be passed to the call as a single string it can be output conditionaly on there being no characters available in the VAL buffer. .skip .i +16 CALL VALTST(N) .skip .lm +16 .i -16 where:##N#######receives the number of characters in the buffer. A reply of CR has zero length. .br If the buffer is empty then: .br N=-1 terminal input .br N=-2 CLONE input .skip .lm -16 .skip 6 .tp 10 VALQIO - Queue an input request and return immediatly .p This routine is used when simultainious input is required on two devices, or when the terminal input completion is to be used to break into some continuing operation. It should be used with great care as some quirks of RSX terminal input can lead to strange phenomena. .skip calling format: .skip .i +16 CALL VALQIO(NAME,PROMPT,IEFN) .skip On return IEFN contains an event flag associated with the request. This flag is cleared at issuance and will set when the request completes. Once VALQIO has been called VALTST may also be used to determine if the request has completed. After VALQIO has been called any of the normal VAL routines may be used to complete the operation, if not yet complete, a wait is performed. This routine behaves identically for terminal and CLONE input. .skip 6 .tp 10 VALREC - record a value to CLONE .p These routines have effect only when a program is running under CLONE control. They transmit values to CLONE which may then retrieve them with the GET command. This permits two way communication between CLONE and the task and enables programs to be written which give CLONE access to complex data structures without the need to modify CLONE itself. .p There are currectly three record routines: .skip .lm +16 .nofill RECINT - To record an integer value RECSTR - To record a string value RECLOG - To record a logical value .skip .fill .lm -16 These routines all have the general form: .skip .i +16 RECxxx(NAME,VAL) .skip .lm +16 .i -16 where:##NAME####is an optionaly null name by which CLONE can retreive the value. CLONE V003 ignores this parameter. .i -8 VAL#####is an integer for RECINT .i -8 VAL#####is a zero terminated string of up to 80 characters for RECSTR .i -8 VAL#####is an integer representing a logical value for RECLOG .br 0=false, else true. .skip .lm -16 .skip 6 VALPBS - put a string (back) into the VAL buffer .p This routine can be used to permit more than one of the VAL routines to attempt to interpret a command. .skip .i +16 CALL VALBPS([STR,[L]]) .skip .lm +16 .i -16 where:##STR#####is the string to be put back .i -8 L#######is the length of STR. If L is null the string is read to a zero byte. .skip .lm -16 If STR is null the string is read from the current OUTS buffer. Thus: .skip .i +16 CALL OUT('_#_#_#._#_#_#',A); CALL VALPBS .skip pushes the value of A into the input buffer. The next input call will then read A. This provides an interesting means of performing inter-task communication as the next input request may be issued by another task. .p If the buffer is too full to accomodate the string it will be truncated at the first space. .skip 6 .tp 10 VALSAV - specify error routines at runtime .p This routine permits the routines called on certain error and exception conditions to be changed dynamically. Routines specified as arguments to this call must be declared EXTERNAL. .skip .i +16 CALL VALSAV(CLOSE,ABORT,IERROR,RERROR,DERROR,OERROR,LINE) .skip .lm +16 .i -16 where:##CLOSE###is a routine to be called by FINISH to perform any cleanup operations. No arguments are passed. .i -8 ABORT###is a routine to be called when the reply to an input request is CNTRL-Z. No arguments are passed. .i -8 IERROR .i -8 RERROR .i -8 DERROR .i -8 OERROR##are error processor routines for: Integer, real, directory lookup and other errors. Arguments are described in Appendix 1. .i -8 LINE####is the OUTS line number parameter to be used for the output of error messages. .lm -16 .skip Any or all arguments may be specified. The current routine is not changed for null arguments. .skip 6 .tp 10 ITESTF - test the state of the terminal global event flag. .p This function tests and modifies the global event flag which is assigned uniquely by START to each terminal. The Function result is the state of the flag on return from the call. .skip .i +16 I=ITESTF([IF][,IGEFN]) .skip The first argument if present is written as the state of the flag the second argument if present receives the gef number on exit from the routine. .skip 6 .tp 10 TTYTST - connect to asyncronous input character AST .p This routine enables output to be performed on a terminal whilst at the same time accepting input characters from the terminal. It also enables characters to be input without waiting for CR. .skip .i +16 CALL TTYTST(ICH[,LUN]) .skip ICH is cleared by the call and remains zero until a character is typed on TI:. If a lun is specified it is used for input otherwise 6 is assumed. When a character is entered ICH receives its ascii value. TTYTST must then be called again if another character is to be read. While a request is current the terminal is attached thus any other task (ex. CLONE) attempting to write to the terminal will hang. If a detach is to be performed when no character has been recieved, TTYTST may be called with the first argument null. TTYTST can be used independantly of the other VAL routines and does not require a prior call to START. .skip 6 .tp 10 ATTACH,DETACH - Attach or Detach a device .p These routines are used to provide a simple means of assigning a LUN to a device and attaching that device. Once a device has been attached it may only be used by the issuing task. Any I/O attempt from another task will be blocked until the a detach is issued or until the attached task exits. This routine incorperates a timeout in the attach so that a program may take alternative action if a device is not available. .skip .i +16 CALL ATTACH(LUN,[IDEV],[IUNIT],[IWT],[IERR]) .skip .lm +16 .i -16 where:##LUN#####is an available logical unit number .i -8 IDEV####is the name of the device to assign lun to and to attach. If this argument is null the current assignment of lun is used. .i -8 IUNIT###is the unit number of the device to be assigned and attached. .i -8 IWT#####is a number of seconds to wait before timeing out on the attach. If this argument is not specified no timeout will be issued. .i -8 IERR#### is a status return, -ve on error. This location will receive a value of IE.DAA (-8) if the device is stll attached by another task when the timeout completes. .lm -16 .skip ATTACH may be used independantly of the other VAL routines and does not require a prior call to START. .pg .subtitle ###############Tailoring VAL .figure 3 .center APPENDIX 1 .skip 2 .center TAILORING THE VAL SYSTEM .skip 2 .p Certain changes in the VAL configuration are possible both at TKB-time and at run-time; these are described below. .skip 2 Changing the CTRL-Z processor routine. .p When CTRL-Z (or CTRL-G or CTRL A) is typed as a reply to a question an abort processor routine is called. A routine called ABORT is required at TKB time and if not supplied explicitly as an input module will be fetched from UTYLIB. The default routine prints the message: .skip .i +16 VAL - USER ABORT .skip and calls FINISH to terminate the program. If more complex processing is required a routine called ABORT may be included in the program and will be linked instead of the default. No arguments are passed to ABORT thus any data required by an abort routine must be placed in COMMON. Within an abort routine no VAL input may be performed, the only VAL routine which is valid is FINISH. If a return is executed in an abort routine the question to which CTRL-Z was replied is reposed and the program continues normaly. .p An abort routine may also be specified at runtime by a call to VALSAV. In this case an EXTERNAL statement must be provided for the routine and a call to VALSAV issued specifying the routines name. This permits the action to be taken on CTRL-Z to be changed between different parts of a program. .skip 2 Input error reporting .p The routines used for reporting errors such as out of range values are linked by default from the module VALERR. If the user wishes to change any of these at TKB time a new module must be provided with the specification below. Individual routines may be specified as for ABORT by calling VALSAV at runtime. .skip 2 .p The first three arguments passed to all of these routines have the same format: .lm +8 .i -8 .skip LUN#####LUN number to use for message output .i -8 LINE####OUTS line number for message output. This is only meaningful to OUTS. .i -8 LBUF####the current input buffer. The first byte of this buffer contains the index at which the error occured. .skip 2 INTERR(LUN,LINE,LBUF,IVAL,ILOW,IHIGH) reports errors from INTVAL .skip REAERR(LUN,LINE,LBUF,RVAL,RLOW,RHIGH) reports errors from REAVAL .skip DIRERR(LUN,LINE,LBUF,IVAL,ILOW,IHIGH,DIR) reports errors from DIRVAL .skip OTHERR(LUN,LINE,LBUF) reports any other errors, such as bad characters .skip CLRERR(LUN,LINE) is called when an error condition is removed. It has no effect. .skip .lm -8 .skip 6 APR USAGE .p The default APR used for mapping the val common is 7. The result of this is that the address range 160000-177777 is not available to a VAL task and that the maximum task size is thus reduced to 28K. However if APR 7 is involved in the mapping of a resident library or a similar external region which does not contain VAL argument buffers VAL will save and restore APR 7 mapping during each call. For tasks which require other mappings of APR 7 the value used by VAL may be changed with TKB by patching the global VALAPR: .skip .i +16 GBLPAT=VALAPR:6 .pg .subtitle VAL implementation notes .figure 3 .center APPENDIX 2 .skip 2 .center VAL IMPLEMENTATION NOTES .skip 2 .p This section discusses the external details of the VAL implementation. The precise internal details may be obtained from the sources themselves. .p The sysgen requirements for a system which supports the package are: .skip .list .le A mapped RSX-11M V3.2 system. .le Memory management directives. .le Send receive directives. .le send/receive by referance directives .le Stop/unstop directives .le The system must contain a system controled partition named VALPAR of size at least 128. words. .end list .skip .p VAL routines access two data structures. First a small buffer VALIMP which contains parameters specific the the task currently executing the beginning of VALIMP is the control block used by the routine READIT for parsing data. Contained within VALIMP is also the address of a dynamic region which is common to all VAL tasks active on the specific TI:. This dynamic region named VALRxx, where xx is the TI: unit number is created in the partition VALPAR. The current size of the dynamic region (generaly called VALCOM) is 128. words thus VALPAR must be sufficiently large to support as many commons as there will be simultainiously active terminals. VALCOM is created when the first VAL task is run on the terminal. Subsequently calls to GOTASK, CHAIN and FINISH transfer a referance to the common between tasks making the data within available to all tasks called in this way. VALCOM is deleted by the system when the last VAL task exits on the terminal. .p The principal contents of VALCOM are: .skip .list .le The input line buffer. This is an 80. char. buffer used to receive all lines of input typed. A current pointer is maintained in this buffer to indicate the next item to be read. .le The prompt buffer. This is an 80. char. buffer which during an input request contains the prompt to be used for the request. It permits a command language processor to issue requests on behalf of a task. .le A 16 word buffer used for user intertask communication. The contents of this buffer are used to transmit small ammounts of information beteen tasks. The first 6 words are pre-determined and are defined under START. .end list .skip In addition VALCOM contains various flags and pointers which indicate the current status and which transmit information to the command language system. .p The precise structure of VALIMP and VALCOM is defined in the package prefix file VALMFD. This file also contains macro definitions used by the package and bit values for the flags words.