ALEDA User Documentation Aleda was written by Dennis V. Jensen of the Ames Laboratory at Iowa State University as part of U.S. Department of Energy contract W-7405-ENG-82. The right to use this software release is allowed in the public domain. The author, Ames Laboratory, and USDOE assume no responsibility as to the correctness of the code nor the appropriateness for such use as it may be applied. Any comments about the Aleda Library may be directed to the author at 258H Development, Ames Laboratory, Ames, Iowa 50011. 1.0 Introduction ____________ Aleda is designed for the Fortran programmer to gain access to serial ports for device interfacing and for user interaction. This library of subroutines provides defaults for missing parameters wherever possible yet maintains a versatile programmable approach to interfacing. The nucleus of Aleda will detect the operating system environment (RT-11 or TSX-Plus) and adapt appropriately. This is based on options configured in a device table and possibly overriden by the user's program at run time. The ability to implement overlapped I/O and computation (asynchronous processing) is included. Response to error conditions is also programmable. An Aleda routine is invoked with any of the following forms: Call Lprog ( ... ) Ierror = Lprog ( ... ) If ( Lprog( ... ) ) goto 1.1 The Functional Value of Aleda subroutines ___ __________ _____ __ _____ ___________ All Aleda routines are setup as function subprograms and return an integer as the functional value of the call. The values returned indicate the result of processing the call. These routines may also be accessed using the FORTRAN CALL statement. When using the CALL statement it would be wise to always include the optional Return Code parameter to verify that the routine terminated with no errors. ALEDA User Documentation PAGE 2 Aleda Conventions 1.2 Required and Optional Parameters ________ ___ ________ __________ Aleda subprogram parameters are classified as either required or optional. Required parameters are necessary for the routines to carry out their specified task. An error code is returned if a required parameter is not provided. Generally the required parameters are at the beginning of the parameter list and optional parameters are at the end. Optional parameters are those that need not be provided in the call list. They are optional because they have default values, or they return supplemental information that is not necessary to complete the specified operation. Parameters are positional; they must always occupy the same position in the call list. Null parameters are those that do not specify a variable or constant at an optional parameter position in the list; the delimiting commas are present or less than the maximum number of parameters are specified. Note: One restriction currently exists for LGETI2 and LGETR4. They currently require that trailing commas exist for all non-specified optional parameters. This is because they are written in Fortran and cannot correctly determine if the parameters exist unless an actual null entry is in the user's call list. This restriction will be corrected in the near future. 1.3 Return Code Parameters ______ ____ __________ Return codes are associated with most Aleda routines. If the return code is NEGATIVE then this code is an Aleda ERROR CODE. The return code value will be the same as the functional value of an Aleda routine when an error has occured. After the SUCCESSFUL COMPLETION of an Aleda routine, the return code will typically be ZERO. For some Aleda routines, the successful return code will be a count of characters transfered. For routines which interact with the user, a return code value of ONE indicates a processing BREAK REQUEST. For this case, the functional value of an Aleda user interaction routine can be non-zero without being an actual error. (Refer to the description of each routine to know how to interpret specific return codes.) 1.4 Error Codes _____ _____ Aleda indicates that processing errors have occurred by returning a negative functional value for the call that detected an error. In addition, if an optional Return Code parameter was provided, it too will be assigned the same negative value. A list of the defined error codes and a brief description of their meaning is provided in a table at the end of this document. ALEDA User Documentation PAGE 3 Aleda Conventions The routine LERROR will evaluate an Aleda error code and list at the console the error number and the associated description. Using optional LERROR parameters a user can include in the error message text additional information specific to the program to help locate the exact point and/or cause of the error. 1.5 Control Word Parameters _______ ____ __________ Some Aleda routines have an optional control word parameter. The value of this parameter specifies variations in the type of processing a particular routine will do. To enable more than one optional processing function it is necessary to sum the individual control word values of each desired function. (Refer to the description of each routine to know what control word options are available.) 1.6 Logical Unit Numbers _______ ____ _______ A connection to a serial port is established through a logical unit number. Each logical unit number associates with a device descriptor that provides all information and working storage for correctly interfacing with a device or terminal port. There is a logical unit for each input and each output stream. For example, the console keyboard is unit zero (0) and the console display is unit one (1) by convention. All other units can be defined in addition to these to be such things as a device supported under RT-11 using direct interrupts (DLv11-types of interfaces), as a TSX-Plus Communication Line (CL) type of device, and/or dynamic configuration to adapt to either of these depending on which system is being run. The device table is configured in Macro-11. The details for configuring these tables are documented in the Macro files *dev*.mac . Typically, this can be configured for your system once and used thereafter. Some modifications can be applied from the Aleda call list for simple changes to the table. A typical device table is included in the library and will be linked into an Aleda program if another table is not explicitly included in the link input files. (See CLTABL.MAC which is the distributed device table included in the library.) For interfacing to devices, the unit number is always required. For interfacing to the user, the unit number is never specified because units 0 and 1 are always used to talk to the user's terminal. Units 2 and 3 would typically be the input stream and output stream of the first device being interfaced. The maximum unit number is configured internally as 24 but can be easily changed in the ALV51C module (DEVICES==24.). ALEDA User Documentation PAGE 4 Aleda Conventions 1.7 The Macro Call Conventions ___ _____ ____ ___________ Aleda provides access to facilities which were originally developed in Macro-11. Within the source files these routines are known as Alvin. Alvin provides more capabilities than available at the Fortran level but with associated complexities in their use. The source for these routines are well documented. For brevity, many of the details are not included here and the user will for now have to refer to the source to gain more information. To aid in using Alvin, the $Alvin macro is defined in the Alvin.MLB macro library. $Alvin defines table offsets of relevant descriptors and other structures which are used internally. In a future release more documentation will be included on these extended features. 1.8 RT-11 Interrupt Considerations _____ _________ ______________ When running under RT-11, the interrupts will be processed by inline service routines. To be generally executable under all monitors and to avoid interference with the user's program, no .DEVICE protection is provided automatically within Aleda. A device can be dynamically enabled and then disabled when not in use, though. And NOABORT can be added to the console device definition (see DLTDEV) to prevent control-C aborts and to allow soft error reporting. For example, an LBREAK will detect a control-C, then a call to ALVEXI will disable all active devices, after which a program can STOP with no repercussions. Of course, under the SJ monitor active interrupts are not an issue as a bus reset will be issued on abort. When an interrupt is enabled, the exact contents of the vector and CSR are retained. These are restored when the device is disabled. Therefore, what Aleda taketh, it giveth back to be as it was before the enable. ALEDA User Documentation PAGE 5 Detailed Description of Aleda Device Interfacing Routines LENABL 2.0 Description ___________ Fortran callable subroutine to enable the specified logical unit number for the transfer of characters. 2.1 Calling Sequence _______ ________ Ierror = LENABL ( Unitnumber, [Buffer], [BufferSize], [ReturnCode], [ControlWord], [CSR], [Vector], [AssociatedUnit] ) 2.2 Parameter Description _________ ___________ Unitnumber: Required parameter. Logical unit number of device to be enabled. Buffer: Optional parameter. Array which will be used as the circular Buffer into which data will be written by the specified logical unit. BufferSize: Optional parameter. Size in bytes of the buffer mentioned above. Buffers must be at least 20 bytes long. ReturnCode: Optional parameter. Variable which, after the call, will contain a numeric value indicating the success or reason for failure of a particular call. ControlWord: Optional parameter. Value indicates certain optional processing functions are to be performed. No optional functions are currently defined for this routine. CSR: Optional parameter. Address of the Control Status Register of the device to be enabled. (Applicable to RT direct interrupt support only.) Vector: Optional parameter. Interrupt vector of device to be enabled. (Applicable to RT direct interrupt support only.) AssociatedUnit: Currently not used. ALEDA User Documentation PAGE 6 Detailed Description of Aleda Device Interfacing Routines LDSABL 3.0 Description ___________ Fortran callable subroutine to disable the specified logical unit number. I/O will be prohibited on the unit after the disable. All interrupt linkage will be reverted to the state prior to enable. 3.1 Calling Sequence _______ ________ Ierror = LDSABL ( UnitNumber, [ReturnCode] ) 3.2 Parameter Description _________ ___________ UnitNumber: Required parameter. Logical unit number of device to be disabled. ReturnCode: Optional parameter. Variable which, after the call, will contain a numeric value indicating the success or reason for failure of a particular call. ALEDA User Documentation PAGE 7 Detailed Description of Aleda Device Interfacing Routines LGETLN 4.0 Description ___________ Fortran callable subroutine to access the specified logical unit number for transfer of characters to the user specified buffer. 4.1 Calling Sequence _______ ________ Ierror = LGETLN ( UnitNumber, Line, LineSize, [ReturnCode], [ControlWord], [TerminatorArray] ) 4.2 Parameter Description _________ ___________ UnitNumber: Required parameter. Logical unit number of the device from which characters are to be transferred. Line: Required parameter. Array into which characters from the specified logical unit will be transferred. LineSize: Required parameter. Size in bytes of the buffer LINE mentioned above. ReturnCode: Optional parameter. If positive- number of characters transferred into LINE on the current call. Else- error code. ControlWord: Optional parameter. Value indicates certain optional processing functions are to be performed. 0 Do not perform any special processing. 1 Interpret the characters in the user specified TerminatorArray as end-of-line characters. 2 Include the parity bit when doing character transfer. TerminatorArray: Optional parameter. String of characters which will be interpreted as end-of-line characters. The first byte of a this array is the number of characters which are terminators, then each terminator byte follows immediately in the array. ALEDA User Documentation PAGE 8 Detailed Description of Aleda Device Interfacing Routines LPUTLN 5.0 Description ___________ Fortran callable subroutine to output characters from a user specified line buffer to a specified logical unit number. 5.1 Calling Sequence _______ ________ Ierror = LPUTLN ( Unitnumber, Line, LineSize, [ReturnCode], [ControlWord], [TerminatorArray] ) 5.2 Parameter Description _________ ___________ UnitNumber: Required parameter. Logical unit number of the device to be written to. Line: Required parameter. Array to hold the characters which will be output to the device specified by the unit number. LineSize: Required parameter. Size of the buffer array LINE in bytes. ReturnCode: Optional parameter. Number of characters actually transferred to the specified device on the current call. ControlWord: Optional parameter. Value indicates certain optional processing functions are to be performed. TerminatorArray: Optional parameter. String of characters which will be interpreted as end-of-line characters. The first byte of a this array is the number of characters which are terminators, then each terminator byte follows immediately in the array. 5.3 Control Word Value Description _______ ____ _____ ___________ 0 Do not perform any special processing. 1 Interpret the characters in the user specified TerminatorArray as end-of-line characters. 2 Include the parity bit when doing character transfer. 8 Output any terminator encountered along with the other characters. ALEDA User Documentation PAGE 9 Detailed Description of Aleda Device Interfacing Routines LRECEV 6.0 Description ___________ Fortran callable subroutine to initiate the transfer of characters from the specified logical unit number to an user specified circular buffer. An LRecev is required before the first LGetLN to a specified logical unit. Subsequent LRecev's are optional and can be used to accomplish such things as flushing the current contents of the circular buffer (control option RESET). 6.1 Calling Sequence _______ ________ Ierror = LRECEV ( UnitNumber, [Buffer], [BufferSize], [ReturnCode], [ControlWord] ) 6.2 Parameter Description _________ ___________ UnitNumber: Required parameter. Logical unit number of the device on which the character transfer is to be initiated. Buffer: Optional parameter. Array which will be used as the circular buffer into which data will be written by the device specified by UnitNumber. BufferSize: Size of the circular buffer in bytes. If size = 0, then the buffer is presumed to already be initialized ReturnCode: Optional parameter. Variable which, after the call, will contain a numberic value indicating the success or reason for failure of a particular call. ControlWord: Optional parameter. Value indicates certain optional processing functions are to be performed. Alvin receive functions PARON, PAROFF, SILENT, and RESET are available. (No echo is SILENT=10000 octal, buffer RESET=1000 octal) ALEDA User Documentation PAGE 10 Detailed Description of Aleda Device Interfacing Routines LERROR 7.0 Description ___________ Fortran callable subroutine to output to the console a message associated with ALEDA error return codes. 7.1 Calling Sequence _______ ________ Ierror = LERROR ( ErrorCode, [Value], [UserLine, Count] ) 7.2 Parameter Description _________ ___________ ErrorCode: Required parameter. Numeric error code value returned by one of the other ALEDA routines. Value: Optional parameter. Numeric value supplied by the user which will be printed at the console along with the associated ALEDA error message. UserLine: Optional parameter. Character string supplied by the user which will be printed at the console along with the associated ALEDA error message. Count: Required parameter if parameter UserLine specified, otherwise ignored. Number of characters in character string UserLine. ALEDA User Documentation PAGE 11 Detailed Description of Aleda Device Interfacing Routines LCNVTD 8.0 Description ___________ Fortran callable subroutine to convert a two byte integer value to a character string representing the decimal equivalent of that value. The value of the optional parameter CONTROL WORD determines the format of the string returned. 8.1 Calling Sequence _______ ________ Ierror = LCNVTD ( Value, Stringbuffer, [Returncode], [ControlWord] ) 8.2 Parameter Description _________ ___________ Value: Required parameter. Integer*2 value which the character string returned will represent. StringBuffer: Required parameter. Area into which the character string representation of value will be placed. This buffer should be seven bytes long. ReturnCode: Optional parameter. Number of valid characters in the converted string. This value should be used in printing the string returned because, with certain formatting options, StringBuffer may contain garbage characters beyond the first ReturnCode number of characters. ControlWord: Optional parameter. Value determines the format of the string returned. 8.3 Control Word Values and Associated Formats _______ ____ ______ ___ __________ _______ 0 (default) Left justify string in buffer with no trailing decimal point. 1,3 Right justify string in first 5 positions of buffer if value was positive, or first 6 positions if string has a minus sign. The string will contain leading zeroes and will not include a decimal point. 2 Same format as ControlWord = 1, except any leading zeroes will become blanks. 4 Left justify string and include trailing decimal point. 5,7 Right justify string in first 6 positions of buffer if value was positive, or first 7 positions if value was negative. The last valid character in StringBuffer will be a decimal point and the string will include leading zeroes. 6 Same format as ControlWord = 5, except any ALEDA User Documentation PAGE 12 Detailed Description of Aleda Device Interfacing Routines leading zeroes in string will become blanks. ALEDA User Documentation PAGE 13 Detailed Description of Aleda User Interfacing Routines LPUTST 9.0 Description ___________ Fortran callable subroutine to output a string to the console listing device. This routine expects strings to be terminated with a zero byte (null) or a backslash (\). If the string is terminated with a backslash, LPUTST will add a carriage return and a linefeed after the message has been transmitted. The current maximum string length is 256 characters. 9.1 Calling Sequence _______ ________ Ierror = LPUTST ( String, [ReturnCode] ) 9.2 Parameter Description _________ ___________ String: Required parameter. Character string to be output to the console listing device. String must be less than 256 characters long and terminate with a null byte or a backslash. ReturnCode Optional parameter. Value returned will be the number of characters transmitted, if positive, or a negative error code. ALEDA User Documentation PAGE 14 Detailed Description of Aleda User Interfacing Routines LGETI2 10.0 Description ___________ Fortran callable subroutine to prompt for and accept, from the console keyboard, an ascii string representing an Integer*2 value, convert the value to its internal 16 bit representation, and return the value to the caller. Optional default, minimum, and maximum values may be provided. If a default value is provided, it will be displayed along with the caller supplied Prompt. If minimum and/or maximum values are provided, they will be displayed when keyboard input can't be converted to a valid value, eg. entering an alphabetic character in response to the prompt will cause an error message and the minimum and maximum values to be displayed. Prompting will continue until a valid Integer*2 value is provided. 10.1 Calling Sequence _______ ________ Ierror = LGETI2 ( Prompt, Var, [ReturnCode], [Default], [Minimum], [Maximum] ) 10.2 Parameter Description _________ ___________ Prompt: Required parameter. User supplied string which will be output to the console listing device to prompt of input. Var: Required parameter. Integer*2 variable which will contain the internal representation of value input from the keyboard. ReturnCode: Optional parameter. Value will be the number of characters input from the keyboard if there was no error in processing, otherwise it will contain an error code value. Default: Optional parameter. Value that will be returned if a carriage return is entered in response to the prompt for input. Minimum: Optional parameter. Minimum valid input value. Entering a valued less than this will cause an error message and the valid range of input values to be displayed, and the user will be prompted to enter another value. Maximum: Optional parameter. Maximum valid input value. Entering a value greater than this will cause an error message and the valid range of input values to be displayed, and the user will be prompted to enter another value. ALEDA User Documentation PAGE 15 Detailed Description of Aleda User Interfacing Routines LGETR4 11.0 Description ___________ Fortran callable subroutine to prompt for and accept, from the console keyboard, an ascii string representing a Real*4 value, convert the value to its internal 4 byte representation, and return the value to the caller. Optional default, minimum, and maximum values may be provided. If a default value is provided, it will be displayed along with the caller supplied Prompt. If minimum and/or maximum values are provided, they will be displayed when keyboard input can't be converted to a valid value, eg. entering an alphabetic character in response to the prompt will cause an error message and the minimum and maximum values to be displayed. Prompting will continue until a valid Real*4 value is provided. Values may be in decimal or scientific notation, but, either way, input values and values for parameters Default, Minimum and Maximum should all contain a decimal point. 11.1 Calling Sequence _______ ________ Ierror = LGETR4 ( Prompt, Var, [ReturnCode], [Default], [Minimum], [Maximum] ) 11.2 Parameter Description _________ ___________ Prompt: Required parameter. User supplied string which will be output to the console listing device to prompt for input. Var: Required parameter. Real*4 variable which will contain the internal representation of value input from the keyboard. ReturnCode: Optional parameter. Value will be the number of characters input from the keyboard if there was no error in processing, otherwise it will contain an error code value. Default: Optional parameter. Value that will be returned if a carriage return is entered in response to the prompt for input. Minimum: Optional parameter. Minimum valid input value. Entering a valued less than this will cause an error message and the valid range of input values to be displayed, and the user will be prompted to enter another value. Maximum: Optional parameter. Maximum valid input value. Entering a value greater than this will cause an error message and the valid range of input values to be displayed, and the user will be prompted to enter another value. ALEDA User Documentation PAGE 16 Detailed Description of Aleda User Interfacing Routines LGETYN 12.0 Description ___________ Fortran callable subroutine to access the console input device for a yes or no response to a question. This routine will return a 1 if a break was requested, a 2 if a yes response was entered, and a 3 if a no response was entered. These return values imply that the routine completed normally. Negative return values are ALEDA errors. The user supplies the prompt for input. 12.1 Calling Sequence _______ ________ Ierror = LGETYN ( Prompt, [ReturnCode] ) 12.2 Parameter Description _________ ___________ Prompt: Required parameter. User supplied string which will represent a question having a yes or no answer. LGETYN will automatically append a question mark and a blank to the string. ReturnCode: Optional parameter. Integer variable which will, after returning, contain the same value as the functional return value of the routine, ie. 1 = break requested, 2 = a yes response was entered, 3 = a no response was entered, and negative value = an ALEDA error occured. ALEDA User Documentation PAGE 17 Detailed Description of Aleda User Interfacing Routines LBREAK 12.0 Description ___________ Fortran callable subroutine to check if the console input device has a pending break request. This routine will return a true functional value if a break has been requested. A repercussion of this routine is that the input buffer will be drained, thus eliminating any characters which may have been typed ahead. This routine is useful to escape from processes on demand. 13.1 Calling Sequence _______ ________ If (LBREAK) Goto Exit ALEDA User Documentation PAGE 18 Appendix A - Aleda Return Codes/Error Codes The following is a brief description of the meaning of each numeric return code. The meaning associated with each value returned should be consistent across all calls to all functions. Return Code Description ______ ____ ___________ 1 Break requested. 0 Normal completion. -1 .. -19 Required parameter n not provided. -20 No device descriptor. -21 Device not enabled. -22 Device already enabled. -23 CSR not in I/O page. -24 Vector out of range. -25 Device is not an input device. -26 Device is not an output device. -27 ALVIN enable failure. -28 ALVIN disable failure. -29 Device already active (Seized) and using a different buffer. -30 Buffer not at least 20 bytes. -31 Buffer not word aligned. -32 Buffer overrun. -33 Terminator processing specified but terminator array not provided. -34 Terminator not found. -35 Input error detected (parity error, character overrun, or framing error). -36 Console is seized. -37 No buffer descriptor for attempted operation. -38 Failed to connect to CL. -39 Could not configure for CL under RT-11 (RT-11 direct interrupt support not genned in). -40 Unit number is out of range. -41 Can not enable this device under TSX-plus. -42 Could not open channel to CL. -43 Direct interrupt table is full. -44 Vector is seized.