ASSIGN

Assigns an I/O path name and attributes TO an I/O object.
 
 ASSIGN @io-path [TO resource] [;attrib [,attrib...]]
ASSIGN @io-path TO *
 
Example:          ASSIGN.BAS
 
Where:
  • resource = device-selector [,device-selector...] | file-specifier | pipe-specifier | BUFFER {string-name$ | numeric-array(*) | [buf-size]}
  • attrib = FORMAT {ON|OFF|MSB FIRST|LSB FIRST} | {BYTE | WORD} | CONVERT {IN|OUT} {OFF | {BY {INDEX|PAIRS} convert$}} | PARITY {EVEN | ODD | ONE | ZERO | OFF} | EOL eol-chars [END] [DELAY seconds] | EOL OFF | RETURN numeric-name | APPEND
  • buf-size = size of the buffer in bytes
  • convert$ = string-name. If INDEX, it can have up to 256 characters. If PAIRS, it must have an even number of characters.
  • eol-chars = string-expression of up to 8 characters
  • seconds = numeric-expression rounded to the nearest 0.001 through 32.767 (default is 0)
 
Usage:
ASSIGN @Code TO Isc;FORMAT OFF
ASSIGN @Close TO *
ASSIGN @Devices TO 711,712,715
ASSIGN @Buf1 TO BUFFER Str1$
ASSIGN @B TO BUFFER [12800]
ASSIGN @Buffer TO BUFFER Array(*)
ASSIGN @File TO "C:\DATA\FILE2"
ASSIGN @File TO "/unix/CityDir/StFile";APPEND
ASSIGN @T TO 12;WORD,RETURN R,EOL My$ DELAY 1
ASSIGN @Stdout TO "| cat";EOL CHR$(10)
ASSIGN @Pipe TO "finger |"
 
Description:

I/O Paths

ASSIGN makes a connection between an I/O path name and a file, buffer, device, or devices. An I/O path contains the necessary information to control the input or output of data. It is used in I/O statements to specify the source or destination of the input or output. An I/O path name can be placed in a COM statement and can be passed by reference as an argument to subprograms. I/O operations can be re-directed by re-ASSIGNing the I/O path. ASSIGN may also be used to change previous I/O path attributes or to close an I/O path.
 

Devices

To do I/O with an IEEE-488 device which has a primary address of 2, you would use the ASSIGN statement (assuming the default IEEE-488 interface select code of 7):
 
ASSIGN @io-path TO 702
 
To do I/O with a device hooked to the serial port (assuming the port is at the default ISC of 9), you would use:
 
ASSIGN @io-path TO 9
 
A device can have more than one I/O path name (each with different attributes) associated with it.
 
An I/O path name can have more than one device assigned to it. If multiple devices are specified, they must be on the same interface. When OUTPUT is made to an I/O path assigned to multiple devices, all the devices receive the data. When ENTER is made from multiple devices, the first device specified sends data to the computer and to all the other devices assigned to the I/O path name. When CLEAR, LOCAL, PPOLL CONFIGURE, PPOLL UNCONFIGURE, REMOTE or TRIGGER are made on multiple devices, all the devices receive the IEEE-488 message.
 

Files

A file is opened when the ASSIGN statement specifies a file-specifier. The file's position pointer is set to the beginning of the file unless APPEND is specified and is updated to point to the next byte to be read or written with each ENTER or OUTPUT statement.
 

Buffers

ASSIGN @Io_path TO BUFFER [300] ! creates an unnamed buffer and assigns it a named I/O path.
 
ASSIGN @Io_path TO BUFFER X(*)
statement assigns an I/O path name to a buffer variable previously declared in a COM, COMPLEX, DIM, INTEGER or REAL statement.
 
The buffer specified in ASSIGN may now be used in ENTER, OUTPUT or TRANSFER statements. Buffer control information can be read with the STATUS statement and includes the current number of bytes in the buffer (initially set to 0), the empty and the fill pointers (initially set to 1) and the buffer capacity.
 
An I/O path name must exist for as long as its assigned buffer exists. To insure this, the following rules are used: Buffers cannot be declared in ALLOCATE statements. For a named buffer and its associated I/O path name, if either appear in a COM block, then the other must also. The same is true of subprogram parameters or else the buffer must appear in a COM block accessible to the subprogram. I/O path names assigned to unnamed buffers cannot appear in COM blocks or subprogram parameters.
 
Unnamed buffers can only be accessed through their I/O path names. When the I/O path of an unnamed buffer is closed, the buffer space is deallocated. Named buffers can be directly accessed through their variable names, although this is not generally recommended. It does not perform necessary byte order swapping. And the data in the buffer can be changed without proper update of the buffer control registers (empty and fill pointers, current number of bytes). To automatically update the buffer control registers use the ENTER, OUTPUT, and TRANSFER statements.
 
Binary data in a buffer exists in the byte order of the data source. If that order is different than the byte order of the computer, then accessing the data through the variable name results in incorrect data. Again, using ENTER, OUTPUT and TRANSFER to access the data handles the byte order correctly.
 

FORMAT

The FORMAT option controls whether data is handled in binary or ASCII. If FORMAT is not explicitly specified a default format is used as specified in the following. In addition to the HP BASIC compatible FORMAT ON and FORMAT OFF options, HTBasic also allows the FORMAT MSB FIRST and FORMAT LSB FIRST options. These options allow explicit specification of the data byte ordering. If LSB FIRST is specified, then numbers are sent and received with the Least Significant Byte first. If MSB FIRST is specified, then numbers are sent and received with the Most Significant Byte first.
 
LSB is the native byte order for HTBasic. If a device is capable of sending binary data in LSB format, it should be instructed to do so and FORMAT LSB FIRST should be specified instead of FORMAT OFF.
 

BYTE and WORD

When BYTE is included in the ASSIGN statement the data is sent and received as 8-bit bytes. WORD sends and receives data in 16-bit words and can only be used on a 16-bit interface. The default form if neither BYTE nor WORD is explicitly specified is BYTE.
 

CONVERT

When CONVERT is included in the ASSIGN statement a character-conversion table is used during OUTPUT and ENTER operations (OUT converts during OUTPUT and IN converts during ENTER). The default attribute is no conversion (CONVERT IN OFF and CONVERT OUT OFF). If CONVERT OUT is specified then conversions are made after EOL characters are appended but before parity generation (if PARITY specified). If CONVERT IN is specified then conversions are made after parity check but before item or statement terminators are checked.
 
When BY INDEX is included, an index system is used in the conversion process. Each original character is used as an index into the conversion string. CHR$(1) is replaced by the 1st character, CHR$, (2) is replaced the 2nd character, etc. Note however that CHR$, (0) is replaced by the 256th character in the conversion string.
 
When BY PAIRS is included, pairs of characters are used in the conversion process (the original character and its replacement character). The original characters (odd characters) are searched in the conversion string. If the original is found it is replaced by the next (replacement) character. If the original is not found, then no conversion takes place.
 

PARITY

The most significant bit of the byte is considered the parity bit. On OUTPUT, parity is calculated after any CONVERT. On ENTER, parity is checked before any CONVERT.
 
Note: The PARITY option to ASSIGN is not supported in HTBasic. The parity for the serial interface should be set using the appropriate CONTROL register.
 

EOL

The default End-Of-Line is a carriage-return (CR) and line-feed (LF) sent with no END indication and no DELAY. Specifying END causes an interface specific END indication to be sent with the EOL. On the IEEE-488, END causes EOI to be sent with the final character of the EOL. Specifying DELAY causes the computer to pause for the specified number of seconds after sending the EOL and before allowing the program to continue. The delay time depends on the timing resolution available on the computer you are using. The default EOL can be restored by specifying EOL OFF.
 
Note: LF or CR/LF are always used to terminate ENTER data, regardless of the setting of EOL in the ASSIGN statement.
 

RETURN

RETURN can be used with ASSIGN to test whether the ASSIGN operation was successful. If not successful the error number is returned in the variable specified, otherwise a zero is returned.
 

APPEND

If APPEND is specified, the file position is moved to the end-of-file after the ASSIGN. If it is not specified, the file position is moved to the beginning of the file. APPEND is supported on BDAT and regular files, but not LIF ASCII files.
 

Close I/O Paths

Closing an I/O path makes the path invalid. All subsequent ON event statements for the closed I/O path are not acted upon. If an I/O path name has not been declared in a COM statement it may be closed in the following ways:
 
1. Explicitly close a path by executing: ASSIGN @io-path TO *
2. Re-assigning the I/O path: ASSIGN @path TO resource
3. Exiting the subprogram: SUBEND, SUBEXIT, ON...RECOVER, or RETURN...
4. Stopping the program: END, GET, LOAD, SCRATCH, SCRATCH A, SCRATCH C or STOP
If an I/O path name has been declared in a COM statement it may be closed in the following ways:
1. Explicitly close a path by executing: ASSIGN @io-path TO *
2. Executing SCRATCH A or SCRATCH C
3. Executing EDIT, GET, LOAD in a program that has a COM statement that does not match the COM statement that contains the I/O path name.
 

Changing Attributes

The attributes of a previously ASSIGNed I/O path may be individually changed by omitting "TO resource" in the ASSIGNstatement. To restore all default attributes use ASSIGN@io-path.
 

ASSIGN TO WIDGET

 

Widget Handles

The ASSIGN statement can also be used to:
  • Create a new level-0 widget
  • Create a widget as a child of an existing widget
  • Create a transient widget
  • Destroy an existing widget
 
Within the ASSIGN statement, a "widget handle" (equivalent to an I/O path) is associated with the new widget. The widget handle can be used in subsequent statements, such as STATUS, CONTROL, and ON EVENT, to control the appearance and behavior of the widget.
 
Also, the widget handle names the widget to be destroyed when ASSIGN@widget-handle TO * is used to destroy a widget.
 

PARENT Option

If no parent is specified when creating a new-widget, the widget is said to be a "level-0" widget.  A level-0 (Zero) widget is not constrained to be within another widget, and may exist at any place in the HTBasic output window.  The X and Y coordinates of the widget are relative to the upper-left corner of the HTBasic output window.
 
Only level-0 widgets may include a title bar, a resize border, and a system menu.  The title bar and resize border allow you to change the position and size of the widget.  If a parent is specified, the new widget will be treated as a "child widget" of its parent.  If you attempt to move a child widget outside the border of the parent widget, the child will be "clipped" at the parent widget’s borders.  The child widget’s X and Y coordinates are relative to the upper-left corner of the parent widget.
 
Not all widgets can be parents, and not all widgets can be children of parent widgets.
 

TRANSIENT Option

The TRANSIENT option is used primarily when the resulting widget is to function as a dialog.  If you create a widget using the TRANSIENT option, other non-transient widgets cannot be placed on top of the widget.
 
If the transient widget has a parent, the transient widget is not restricted to lie within the bounds of its parent as are other child widgets.  Visually, the transient widget appears to be a special type of level-0 widget.
 

SET Option

All widgets have a variety of attributes that control their appearance and behavior.  You can initialize the values of these attributes at the time of creation of the widget by using the SET option.
 
Attributes are either scalar (may contain a singel value) of vector (may be assigned an array of values) and have value of either numeric or string type.
 

Shorthand: Assigning Attributes

You can use a shorthand method to assign values to several scalar attributes without naming them individually on the ASSIGN statement.  To do this, you store all the attributes in a string array and all the matching values in another array of the same size.
 
Then, when you specify both array names in the SET option of the ASSIGN statement, the attribute named in each element of the string array will be assigned the corresponding value in the value array.  Elements of the string array that contain nothing, or nothing but blanks, will be ignored.
 
For example:
 
Attribs$(1) = "X"
Attribs$(2) = "Y"
Attribs$(3) = "WIDTH"
Attribs$(4) = "HEIGHT"
Values(1) = 5
Values(2) = 5
Values(3) = 500
Values(4) = 300
ASSIGN @Panel TO WIDGET "PANEL";SET(Attrib$(*):Values(*))
 
See Also:
CREATE, CREATE ASCII, CREATE BDAT, PURGE, ENTER, OUTPUT