Operations Equipment and Measurement Division - Systems Group _____________________________________________________________ Software Documentation ______________________ PRELIMINARY ___________ Subject Fortran Terminal Input Package - 'ASK' _______ Author R J Carpenter ______ Software Version Y07.00 ________________ Document File ASKY07 _____________ Document Version Y07.00 ________________ Issue Date 17 Dec 84 __________ Copyright (C) Shell Research Ltd. 1984 USER DOCUMENTATION FOR THE FORTRAN TERMINAL INPUT PACKAGE 'ASK' Author : R. J. Carpenter DISCLAIMER __________ The copyright in the computer program described in this document and in the associated user instructions is the property of Shell Research Ltd.. The information in this document is subject to change without notice and should not be construed as a commitment by Shell Research Ltd. Shell Research Ltd. assumes no responsibility for any errors which may appear in this document. No guarantee is given or may be implied as to the adequacy of the program or its suitability for any particular purpose and no liability is accepted for any loss or damage arising out of its use. SHELL RESEARCH LIMITED THORNTON RESEARCH CENTRE Operations Equipment and Measurement Division P.O. Box 1 CHESTER CH1 3SH U.K. December 1984. ASK Package - User Documentation 1. INTRODUCTION ____________ This package provides FORTRAN programmers with a capability similar to the IND (ICP) .ASK directives. That is, it allows the programmer to issue a single subprogram call to request an input value from a user. The facilities provided include the ability to define a prompt, to specify the target, to have the response checked for correct syntax, e.g. no 9's in an octal number, and to ensure that the response lies within a specified range. In addition, a default capability is provided for lazy users. 2. GENERAL DESCRIPTION ___________________ The package is arranged as a set of FORTRAN callable subroutines and functions. All the routines are available to FORTRAN-77 users and a large subset of them are availabe to FORTRAN IV users. Most of the routines involve actual terminal I/O, but some of them are concerned with defining the environment in which the package operates. The general form of an input subroutine call is:- CALL ASKx([string],xtarget[,xmin][,xmax][,xdefault]) The general form of an input function call is:- ivar = IASKx([string],xtarget[,xmin][,xmax][,xdefault]) Normally, ivar will contain the number of characters typed by the user (not including the terminator - normally ). If, however special character mode is enabled, by use of the ASKSCE routine, other flag values will be returned. For further information, please section 5.5. If omitted, most arguments assume default values. They are:- string The default string is "[xxxxx] ? ". target MUST be defined, the subroutine performs no operation if this value is missing. min Lower limit checks are skipped if min is not supplied. max Upper limit checks are skipped if max is not supplied. default No default value will be used if default is not supplied. Certain internal consistency checks are performed with regard to min and max. The correct order is min less than, or equal to, max. Failure to observe this rule will result in no limit checking being carried out. Note that if a default value is suplied in the subprogram call and invoked by the user typing alone, limit checks are omitted. This feature may be used by a program as a simple way of detecting when a user has only entered . ASK Package - User Documentation Page 5 The normal output format is :- STRING [x R:min:max D:default] ? Where x = I for a single precision decimal integer O for a single precision octal integer R for single precision real number Y/N for a logical (or in the general case a/b where a and b are the valid responses). S for String M for a monetary value J for a double precision decimal integer min is the minimum value permitted as a response. If this value was omitted from the subroutine call, no value is printed. max is the maximum value permitted as a response. If this value was omitted from the subroutine call, no value is printed. If both min and max are omitted from the subroutine call, the entire element of 'D:min:max' is not printed. default is the default value. If omitted from the subroutine call, the entire element of 'R:default' is not printed. Note that the variable descriptor display (the part enclosed in square brackets []) may be supressed by use of the ASKDSD routine. Also the prompt tail, that is, the '?' part, may be changed by use of the ASKDPS routine. Both routines are described in the Utilities section. Except when accepting string or character variables, the ASK package is not case sensitive, that is, either 'Y' or 'y' is interpreted as yes and 1e2 or 1E2 as 100. For further information on the handling of lower case characters please see the ASKLCD routine in the Utilities section and the Operating System Specifics described in sections 7 and 8. 3. CORE ROUTINES _____________ This section describes in detail each input routine that is available under both FORTRAN IV and FORTRAN 77. 3.1 ASKI/IASKI __________ The ASKI subroutine solicits a decimal INTEGER*2 number from the user. ASK Package - User Documentation Page 6 Form: CALL ASKI([prompt],i[,min][,max][,idftl]) ivar = IASKI([prompt],i[,min][,max][,idftl]) Where: ivar is an INTEGER*2 specification to receive the returned function value. prompt is an optional prompt string. The string may be either a null terminated LOGICAL*1 array or a quoted literal. i is an INTEGER*2 variable or array element to receive the input value. min is an optional INTEGER*2 specification for the lowest value permissible for i. max is an optional INTEGER*2 specification for the highest value permissible for i. idflt is an optional INTEGER*2 specification for the default value for i. 3.2 ASKO/IASKO __________ The ASKO subroutine solicits an octal INTEGER*2 number from the user. Form: CALL ASKO([prompt],k[,kmin][,kmax][,kdftl]) ivar = IASKO([prompt],k[,kmin][,kmax][,kdftl]) Where: ivar is an INTEGER*2 specification to receive the returned function value. prompt is an optional prompt string. The string may be either a null terminated LOGICAL*1 array or a quoted literal. k is an INTEGER*2 variable or array element to receive the input value. kmin is an optional INTEGER*2 specification for the lowest value permissible for k. kmax is an optional INTEGER*2 specification for the highest value permissible for k. kdflt is an optional INTEGER*2 specification for the default value of k. 3.3 ASKR/IASKR __________ The ASKR subroutine solicits an REAL*4 number from the user. Form: CALL ASKR([prompt],z[,zmin][,zmax][,zdftl]) ASK Package - User Documentation Page 7 ivar = IASKR([prompt],z[,zmin][,zmax][,zdftl]) Where: ivar is an INTEGER*2 specification to receive the returned function value. prompt is an optional prompt string. The string may be either a null terminated LOGICAL*1 array or a quoted literal. z is an REAL*4 variable or array element to receive the input value. zmin is an optional REAL*4 specification for the lowest value permissible for z. zmax is an optional REAL*4 specification for the highest value permissible for z. zdflt is an optional REAL*4 specification for the default value of z. 3.3 ASKL/IASKL __________ The ASKL subroutine was designed to solicit a YES or NO answer from the user. A YES response is returned by the target LOGICAL*1 value being set .TRUE. and a NO response being returned as .FALSE.. If, however, qtrue and qfalse are defined, the routine will use these two characters as the valid responses. Please note that both these values must be supplied to overide the defaults values of 'Y' and 'N'. Form: CALL ASKL([prompt],q[,qtrue][,qfalse][,qdftl]) ivar = IASKL([prompt],q[,qtrue][,qfalse][,qdftl]) Where: ivar is an INTEGER*2 specification to receive the returned function value. prompt is an optional prompt string. The string may be either a null terminated LOGICAL*1 array or a quoted literal. q is a LOGICAL*1 variable or array element to receive the input value. qtrue is an optional LOGICAL*1 specification of the character to be input for q to returned as .TRUE.. If omitted, the default value of 'Y' will be used. qfalse is an optional LOGICAL*1 specification of the character to be input for q to be returned as .FALSE.. If omitted, the default value of 'N' will be used. qdflt is an optional LOGICAL*1 specification for the default value. Note that the default value is the character value required, i.e. for a default affirmative response, the default value must be same character as the supplied or default value of qtrue. If the value ASK Package - User Documentation Page 8 is inappropriate in the current context, it will be ignored and no default will be defined. 3.5 ASKS/IASKS __________ The ASKS subroutine solicits an input string from the user. The string is returned null terminated in a LOGICAL*1 array. The maximum size for the input string is 80 characters. See the ASKLCD routine for information on the control of upper to lower-case conversion. Form: CALL ASKS([prompt],qs[,lmin][,lmax]) ivar = IASKS([prompt],qs[,lmin][,lmax]) Where: ivar is an INTEGER*2 specification to receive the returned function value. prompt is an optional prompt string. The string may either be a null terminated LOGICAL*1 array or a quoted literal. qs is a LOGICAL*1 array to receive the input string. This array could contain upto lmax characters plus the null terminator and therefore must be dimensioned to contain at least lmax + 1 elements. If lmax is not specified, the default maximum string length is 80 characters. lmin is an optional INTEGER*2 specification for the minimum length permissible for the input string excluding the null terminator. This value must not be less than -1 nor greater than lmax. The default value is 0. lmax is an optional INTEGER specification for the maximum length permissible for the input string exculding the null terminator. This value must be not less than lmin nor greater than 80. The default value is 80. 4. FORTRAN 77 Specific Routines ____________________________ The following routines are only available to FORTRAN 77 users. Note that not only are the target variables for these routines only applicable in a FORTRAN 77 environment, but that source code for these modules contains FORTRAN 77 language constructs. 4.1 ASKJ/IASKJ __________ The ASKJ subroutine solicits an INTEGER*4 input from the user. Form: CALL ASKJ([prompt],j[,jmin][,jmax][,jdftl]) ivar = IASKJ([prompt],j[,jmin][,jmax][,jdftl]) Where: ivar is an INTEGER*2 specification to receive the returned function value. ASK Package - User Documentation Page 9 prompt is an optional prompt string. The string may be either a null terminated LOGICAL*1 array or a quoted literal. j is an INTEGER*4 variable or array element to receive the input value. jmin is an optional INTEGER*4 specification for the lowest value permissible for j. jmax is an optional INTEGER*4 specification for the highest value permissible for j. jdflt is an optional INTGER*4 specification for the default value of j. 4.2 ASKM/IASKM __________ The ASKM subroutine solicits a monetary value from the user. The user sees a request for a floating point number number in the format Fx.2. However, the value is returned as a fixed point value in an INTEGER*4 variable. Form: CALL ASKM([prompt],jm[,jmin][,jmax][,jdftl]) ivar = IASKM([prompt],jm[,jmin][,jmax][,jdftl]) Where: ivar is an INTEGER*2 specification to receive the returned function value. prompt is an optional prompt string. The string may either be a null terminated LOGICAL*1 array or a quoted literal. jm is the INTEGER*4 variable or array element to receive the input value. jmin is an optional INTEGER*4 specification for the lowest value permissible for jm. jmax is an optional INTEGER*4 specification for the highest value permissible for jm. jdflt is an optional INTEGER*4 specification for the default value of jm. Note ____ Values for jmin, jmax or jdflt are assumed to be in fixed point format with the implied decimal point between the second and third decades, e.g. a value for jmin of 2345 is printed as 23.45. 4.3 ASKC/IASKC __________ ASK Package - User Documentation Page 10 The ASKC subroutine solicits a string input from the user and puts the result in a CHARACTER data type variable. For information on the control of lower to upper case character conversion, please see the description of the ASKLCD routine. Form: CALL ASKC([prompt],c,[lmin],lmax) ivar = IASKC([prompt],c,[lmin],lmax) Where: ivar is an INTEGER*2 specification to receive the returned function value. prompt is an optional prompt string. The string may be either a null terminated LOGICAL*1 array or a quoted literal. c is a CHARACTER variable or array element to receive the input string. Input strings shorter than lmax are padded to the right with spaces. lmin is an optional INTEGER*2 specification for the minimum length permissible for c. This value must be greater than -1 and not greater than lmax. lmax is an INTEGER*2 specification for the length of the charcter variable c. This must be same value as that in the formal declaration of the variable c as a CHARACTER data type. 5. Utility Routines ________________ All the utility routines are available in either a FORTRAN IV or FORTRAN-77 environment. 5.1 ASKCZD ______ This module provides a capability for a programmer to handle ^Z inputs while using an ASK routine. The normal, that is, default condition, is that if ASK detects a ^Z input, it will treat it as an end-of-input command and exit the task. To avoid that situation, the programmer may call this routine with a LOGICAL*1 variable or constant which determines whether ^Z means exit job or is an illegal character. Form: CALL ASKCZD(qczaf) Where: qczaf is a LOGICAL*1 variable or constant. If qczaf is .TRUE. then ^Z's are treated as illegal input. If qczaf is .FALSE. then ^Z's are treated as end-of-task. 5.2 ASKDPS ______ The ASKDPS subroutine allows the (re)definition of the prompt string tail. The normal (i.e. default) is '?'. This may be replaced by any 0 to 3 character string. ASK Package - User Documentation Page 11 Form: CALL ASKDPS(qstrng) Where: qstrng is new tail string, which may be either a null terminated LOGICAL*1 array or a quoted literal. 5.3 ASKDSD ______ The ASKDSD subroutine allows the programmer to suppress the display of the variable descriptor section of the prompt, that is the information added by the ASK package enclosed in square brackets. Note that this not affect the validation of the user's resposnse. Form: CALL ASKDSD(qflag) Where: qflag is a LOGICAL*1 specification. If qflag is .TRUE., the display is suppressed; if qflag is .FALSE., the display is (re)enabled. 5.4 ASKLCD ______ The ASKLCD subroutine allows the programmer to control the conversion of lower to upper case characters during string input, that is, when either ASKS or ASKC (or their function equivalents) has been invoked. The default case is that lower case characters are NOT converted to upper case. Note that other constaints applied by the operating system and/or the terminal handler may mean that no lower case characters may be input anyway. For further information please see the Operating System Specifics in sections 7 and 8. Form: CALL ASKLCD(qflag) Where: qflag is a LOGICAL*1 specification. If qflag is .TRUE., lower to upper case conversion is enabled; if qflag is .FALSE., lower to upper case conversion is disabled. 5.5 ASKSCE ______ The ASKSCE subroutine was written to increase the usefulness of the ASK routines and permit them to be used more effectively in a menu environment. The ASK package contains a "Special Character Enable" flag which, if set, allows the ASK package to respond to certain additional characters normally treated as invalid. To make use of this capability, you must call all the ASK routines as functions, since the status code is returned as the function value, and you must call this routine to enable the special character processing. When enabled the following function values are returned for the characters indicated :- -6 if the user entered ?. -5 if the user entered ^. In addition, if you have ^Z disabled (by using the ASKCZD routine) :- ASK Package - User Documentation Page 12 -4 if the user entered ^Z. If you have video mode enabled (by using the ASKVME routine), normal error messages are suppressed and the following additional values are returned :- -3 The string length entered was not within the range specified. -2 The numeric value entered was not within the range specified. -1 The user input was invalid or inappropriate in the current context. 0 The user entered by itself and the target will contain the default value if one was supplied in the call. Form: CALL ASKSCE(qflag) Where: qflag is a LOGICAL*1 specification. If qflag is .TRUE., special character mode is enabled; if qflag is .FALSE., special character mode is disabled. 5.6 ASKVME ______ The ASKVME subroutine allows the programmer to control two of the functions of the ASK package which would be undesirable in a menu-mode situation with a video screen. The first effect is that ASK will not output a carriage-return/line-feed pair before outputting the prompt string, thus allowing you to pre-positon the cursor exactly where you want the text to appear. The second effect is to suppress the printing of error messages since that may destroy your screen format. Note ____ If you enable this mode, you must call all the ASK I/O routines as functions in order to receive any possible error status returns. Form: CALL ASKVME(qflag) Where: qflag is a LOGICAL*1 specification. If qflag is .TRUE., video mode is enabled; if qflag is .FALSE., video mode is disabled. 6. Error Messages ______________ Providing you have not suppressed them by enabling video mode, the package will generate the following self-explanatory error messages as appropriate :- ASK Package - User Documentation Page 13 ?ASK-F-Input not in range. Please try again ? ?ASK-F-Invalid input. Please try again ? ?ASK-F-String length not in range. Please try again ? ?ASK-F-No default defined. Please try again ? ?ASK-F-Task exiting due to ^Z input. 7. RT11 Specific Information _________________________ 7.1 Linking _______ These subroutines (and other routines which they themselves call) are contained in a library called ASKLIB which must be specified at LINK time. e.g. .LINK MYPROG,ASKLIB or .LINK/LIB:ASKLIB MYPROG or .R LIBR *MYPROG=MYPROG,ASKLIB 7.2 Lower Case Characters _____________________ Note that the ASK package sets the lower case enable bit (TTLC$) in the Job Status Word permitting the entry of lower case characters. This may impact you if you do additional terminal input other than through the ASK package. If you clear TTLC$, it will be set again the next time you call an ASK routine. 7.3 Restrictions ____________ 7.3.1 Prerequisites _____________ This software requires RT-11 V04.xx or later and RT-11/FORTRAN V2.5 or later to operate correctly and cannot be guaranteed for earlier versions. However, it is intended to modify the software as required to run under the new releases of RT-11 and/or RT-11/FORTRAN as and when they become available. 7.3.2 Hardware ________ As this suite contains FORTRAN subroutines, (which are hardware and compiler dependent), it is recommended that the library is used only on the machine on which it was compiled. If this is not possible, great care should be taken to ensure that the host system generates the correct form of FORTRAN object code for the target system. 7.3.3 Multi-terminals _______________ ASK Package - User Documentation Page 14 The current version of this sofware can only be used on the system (or foreground) console terminal. Again it is hoped to remove this restriction and allow input from suitably attached auxiliary terminals. 8. RSX11-M Specific Information ____________________________ 8.1 Task Building _____________ These subroutines (and other routines which they themselves call) are contained in a library called ASKFxx.OLB must be specified at TKB time. If you use the standard command files supplied with the distibution kit the libraries are called ASKFTN for FORTRAN IV, or ASKF77 for FORTRAN-77. It is suggested that these libraries are kept in LB:[1,1] for access by all of the users on the system. e.g. DCL>LINK MYPROG,LB:[1,1]ASKLIB/LIB or MCR>TKB MYPROG=MYPROG,LB:[1,1]ASKLIB/LB As far as it is known, using the ASKFxx library requires no specific TKB options to be specified. 8.2 Lower Case Characters _____________________ Note that the ASK package does not change any of the values in the Terminal Control Block, thus lower case characters will only reach the package if a SET /LOWER=TI: (or equivalent) has been applied to the appropriate terminal. 8.3 Restrictions ____________ 8.3.1 Prerequisites _____________ This software requires RSX11-M V4.0 or later and one of the following language compilers:- FORTRAN IV V2.5 or later or FORTRAN 77 V4.0 or later to operate correctly. However, it is intended to modify the software as required to run under the new releases of RSX11-M and/or FORTRAN IV and/or FORTRAN 77 as and when they become available. 8.3.2 Hardware ________ As this suite contains FORTRAN subroutines, (which are hardware and compiler dependent), it is recommended that the library is used only on the machine on which it was compiled. If this is not possible, great care should be taken to ensure that the host system generates the correct form of FORTRAN object code for the target system. 8.3.3 Terminals _________ The current version of this sofware always uses LUN 5 which is normally assigned to TI: and there is no convenient way of changing the ASK Package - User Documentation Page 15 LUN assignment (short of modifying the source code). One obvious caveat springs from this, and that is please be VERY careful about re-assigning LUN 5 when using any ASK routines. ASK Package - User Documentation Page 16 APPENDIX A __________ Installation Details for RT11 _____________________________ A.1 RT-11 Version 4 ___________________ The following information is for RT-11 version 4 users or for those people who cannot or do not have IND on their version 5 system. Before invoking any of the command files below, please assign the logical device name AV: to the disk that contains the ASK sources. This disk will also be used for for the object modules (which are subsequently deleted), and for the library file. If you want listing, assign the logical device name LV: to your listing device; if you don't then assign NL: to LV: A.1.1 Compilation ___________ To compile all the subroutines, use the command files ASKMAC.COM and/or ASKFOR.COM (for the Macro and Fortran files respectively). To compile any individual routine then use DCL command "COMPILE ASKxxx". A.1.2 Library Creation ________________ To create the user library ASKLIB, use the indirect command file ASKLIB.COM. A.1.3 Complete Build ______________ To do a complete build, that is compilation and library creation, use the indirect command file ASKBLD.COM A.2 RT-11 Version 5 _______________ The following information is for RT-11 version 5 users who have IND on their system disk; if you cannot or do not have IND, then please use the version 4 method. You may build the whole system by entering the command :- IND dev:ASKBLD.CMD You should then answer all the questions as appropriate. ASK Package - User Documentation Page 17 APPENDIX B __________ Installation Details for RSX11-M ________________________________ B.1 RSX11-M Installation Procedure ______________________________ To install the package on an 11M V4 system, move the entire contents of the distribution medium into your favourite UIC and enter @ASKBLD. Assuming the build process completes successfully, then the only thing you have to do (if required) is to login privileged, and copy the appropriate .OLB's into LB:[1,1]. ASK Package - User Documentation Page 18 APPENDIX C __________ Contents of Distribution Kits _____________________________ C.1 RT-11 Distribution Kit ______________________ ASKCOM.FOR ASKACR.MAC ASKBLD.CMD ASKFEC.FOR ASKC .MAC ASKBLD.COM ASKFER.FOR ASKCUC.MAC ASKFOR.COM ASKFIO.FOR ASKDSD.MAC ASKLIB.COM ASKFL .FOR ASKEOF.MAC ASKMAC.COM ASKFNI.FOR ASKI .MAC ASKFNR.FOR ASKJ .MAC ASKFPB.FOR ASKL .MAC ASKFPN.FOR ASKLEN.MAC ASKFR .FOR ASKM .MAC ASKFS .FOR ASKPAD.MAC ASKTIO.FOR ASKPFX.MAC ASKTST.FOR ASKR .MAC ASKRT .MAC ASKS .MAC ASKSCZ.MAC ASKSLC.MAC ASKSPS.MAC ASK Package - User Documentation Page 19 C.2 RSX11-M Distribution Kit ________________________ ASKFEC .FTN ASKACR .MAC ASKBLD .CMD ASKFER .FTN ASKC .MAC ASKFIO .FTN ASKCUC .MAC ASKFJ .FTN ASKDSD .MAC ASKFL .FTN ASKEOF .MAC ASKFM .FTN ASKI .MAC ASKFNI .FTN ASKJ .MAC ASKFNJ .FTN ASKL .MAC ASKFNR .FTN ASKLEN .MAC ASKFPB .FTN ASKM .MAC ASKFPN .FTN ASKPAD .MAC ASKFR .FTN ASKPFX .MAC ASKFS .FTN ASKR .MAC ASKTIO .FTN ASKS .MAC ASKTST .FTN ASKSCZ .MAC ASKSLC .MAC ASKSPS .MAC