CALL - CYCLE

CALL

Supported On UX WS DOS IN*
Option Required None
Keyboard Executable Yes
Programmable Yes
In an IF ... THEN ... Yes

CALL transfers program execution to the specified subprogram and optionally passes parameters to the subprogram.

Example Statements

CALL Process(Reference,(Value),@Path)
CALL Transform(Array(*))
Transform(Array(*))
CALL MySub$
CALL MySub$ WITH (X,Y,A$)


Item Description Range
subprogram name name of the SUB or CSUB subprograms to be called any valid name
string name a simple string variable containing the name of a user-defined subprogram loaded SUBs and CSUBS
I/O path name name assigned to a device, devices, or mass storage file any valid name see ASSIGN)
variable name name of a string or numeric variable any valid name
substring string expression containing substring notation (see Glossary)
literal string constant composed of characters from the keyboard, including those generated using the [ANY CHAR] key --
numeric constant numeric quantity expressed using numerals, and optionally a sign, a decimal point, and/or exponent notation --

Semantics

A subprogram may be invoked by a stored program line, or by a statement executed from the keyboard. Invoking a subprogram changes the program context. Subprograms may be invoked recursively. The keyword CALL may be omitted if it is the first word in a program line. However, the keyword CALL is required in all other instances.

The pass parameters must be of the same type (numeric, string, or I/O path name) as the corresponding parameters in the SUB or CSUB statement. Numeric values passed by value are converted to the numeric type of the corresponding formal parameter. Variables passed by reference must match the corresponding parameter in the SUB statement exactly. An entire array may be passed by reference by using the asterisk specifier.

If there is more than one subprogram with the same name, the lowest-numbered subprogram is invoked by a CALL.

Program execution generally resumes at the line following the subprogram CALL. However, if the subprogram is invoked by an event-initiated branch, program execution resumes at the point at which the event-initiated branch was permitted.

When CALL is executed from the keyboard, the subprogram is executed in its own separate context. Furthermore, the current state of the system determines the system's state when the subprogram executes a STOP. If the computer was paused or stopped when CALL was executed, its state does not change. If the computer was running when the CALL was executed, the program pauses at the program line which was interrupted by the CALL for the subprogram, and resumes execution at that point after the subprogram is exited.

CALL Using String Names

You can specify the subprogram accessed by CALL using either the subprogram name or a string expression that evaluates to the subprogram name. All of the calls to Mysub in the following code segment are legal:

      100 Name$="Mysub"                     using subprogram name with CALL

       110 CALL Mysub(1)                    

       120 Mysub(2)                               using subprogram name without CALL

       120 CALL Name$ WITH (3)                 using string name with CALL

       130 END

         140 !

       150 SUB Mysub(I)

       160 PRINT "HELLO";I

       170 SUBEND

Note that the string name must match the subprogram name exactly, including upper and lower case letters. Also note that you must use the keyword CALL with string subprogram names.

CASE

See SELECT...CASE.

CAT

Supported On UX WS DOS* IN*
Option Required None
Keyboard Executable Yes
Programmable Yes
In an IF ... THEN ... Yes

CAT lists the contents (files) in a specified directory or mass storage volume. CAT can also list selected information about the contents of a program (PROG-type) file.

Example Statements

CAT           ! List contents of current MSI volume/directory.
CAT TO A$(*)  ! List contents of current MSI to string variable.
CAT ":,700,1"   ! List contents of an HP-IB disk at 700.
CAT "Dir1/Dir2" ! List contents of a subdirectory. 
CAT "PROG_File" ! List subprogams in PROG_file.
CAT TO #701     ! List to an HP-IB printer at 701.
CAT "Monday_?"
CAT "*[0-9]*" ! WILDCARDS UX only
CAT ":REMOTE"
CAT ":REMOTE; LABEL Mastervol"
CAT "A/B/C:REMOTE"
CAT "../../.."
CAT "Dir1/Dir2"
CAT "Dir_1/Sub_dir*"
CAT "HFS_Dir";Names
CAT "PROG_File"
CAT;SELECT "D",SKIP Ten_files,NO HEADER
CAT TO String_array$(*)
CAT TO Hfs_dir$(*);EXTEND

Item Description Range
directory specifier string expression; Default=MASS STORAGE IS directory (see MASS STORAGE IS)
volume specifier string expression; Default=MASS STORAGE IS volume (see MASS STORAGE IS)
file specifier string expression specifying a PROG-type file (see drawing)
directory path literal (see MASS STORAGE IS)
file name literal depends on volume's format (see Glossary)
LIF protect code literal; first two non-blank characters are significant > not allowed
SRM password literal; first 16 non-blank characters are significant > not allowed
catalog device selector numeric expression, rounded to an integer; Default=PRINTER IS device (see Glossary)
string array name name of a string array (see text) any valid name
beginning character(s) string expression 1 to 10 characters (LIF); 1 to 14 characters (HFS; short file names); 1 to 255 characters (HFS; long file names); 1 to 16 characters (SRM)
number of files numeric expression, rounded to an integer 1 through 32 767
return variable name name of a numeric variable any valid name

Semantics

The catalog shows information such as the name of each file, whether or not it is protected, the file's type and length, and the number of bytes per logical record.

The file types recognized in HP BASIC are: ASCII, BDAT (data), BIN (binary program), HP-UX, PROG (program), PROG2 (HP BASIC/UX 700 program), DOS (DOS File System), and SYSTM (operating system). An ID number is listed for any unrecognized file types.

See the WILDCARDS statement for more information regarding the use of wildcards with CAT.

LIF Catalogs

The LIF catalog format is shown below. This catalog format requires that the PRINTER IS device have the capability of displaying 65 or more characters. If the printer width is less than 65, the DATE and TIME columns are omitted.

:CS80,700

VOLUME LABEL: B9836
FILE NAME PRO TYPE REC/FILE BYTE/REC ADDRESS DATE TIME
MyProg PROG 14 256 16 23-May-87 7:58
VisiComp ASCII 29 256 30 8-Apr-87 6:00
GRAPH BIN 171 256 59 1-May-87 1:00
GRAPHX BIN 108 256 230 10-Aug-87 9:00

The first line of the catalog shows the volume specifier (:CS80,700 in this example).

The second line shows the volume label--a name, containing up to 6 characters, stored on the media (B9836 in this example).

The third line labels the columns of the remainder of the catalog. Here is what each column means:

FILE NAME lists the names of the files in the directory (up to 10 characters).
PRO indicates whether the file has a protect code (* is listed in this column if the file has a protect code).
FILE TYPE lists the type of each file.
REC/FILE indicates the number of records in the file.
BYTE/REC indicates the record size.
ADDRESS indicates the number of the beginning sector in the file.
DATE indicates when the date the file was last modified.
TIME indicates the time the file was last modified.

HFS Catalogs

In order to perform a CAT of an HFS directory, you need to have R (read) and X (search) permissions on the directory to be cataloged, as well as X (search) permissions on all superior directories.

In order to perform a CAT of an HFS file, you need to have R (read) permission on the file to be cataloged, as well as X (search) permissions on all superior directories.

Here is a typical catalog listing of an HFS directory. Note that a 50 column display truncates this catalog listing after the column with TIME in it. Therefore, the PERMISSION, OWNER, and GROUP columns will be not be listed.

:CS80, 700

LABEL: MyVol

FORMAT: HFS

AVAILABLE SPACE: 60168

FILE NAME FILE

TYPE

NUM

RECS

REC

LEN

MODIFIED

DATE TIME

PERMISSION OWNER GROUP
lost+found DIR 0 32 19-Nov-86 10:47 RWXRWXRWX 18 9
FILEIOD PROG 191 256 21-Nov-86 9:03 RW-RW-RW- 18 9
RBDAT BDAT 2 256 21-Nov-86 9:10 RW-RW-RW- 18 9
CATTOSTR PROG 2 256 1-Dec-86 8:02 RW-RW-RW- 18 9

The first line of the catalog shows the volume specifier (:CS80,700 in this example).

If the directory path specifier contains more characters than the display width, the last 49 or 79 characters (depending on the display width) are shown. An asterisk (*) as the left-most character in the path specifier indicates that leading characters were truncated for the display. In HP BASIC, the device type is always HFS, and no device selector is shown.

The second line shows the volume label--a name, containing up to 6 characters, stored on the media (MyVol in this example). In HP BASIC, the label is not shown.

The third line shows the format of the disk (HFS in this example). In HP BASIC, if the directory being displayed is on an HFS long file name volume (LFN), then the format will be shown as:

          HFS LFN

The fourth line lists the number of available 256-byte sectors on the disk (60168 in this example). If the sector size is 1024 bytes, then each 1024-byte sector would count as 4 256-byte sectors.

The fifth line labels the columns of the remainder of the catalog. Here is what each column means:

FILE NAME Lists the name of the file. HP BASICtruncates file names longer than 14 characters and places an * at the end of the name. Note that CAT;NAMES does display the full name, even on long file name systems.
FILETYPE Lists the file's type (for instance, DIR specifies that the file is a directory; PROG specifies an HP BASIC program file; PROG2 specifies an HP BASIC/UX 700; BDAT specifies a data file; etc.) if you have read permission. If you do not have read permission, the file type is left blank. HP BASIC also has these file types in addition:
  • CDEV, character device file
  • BDEV, block device file
  • SLINK, symbolic link without a valid target
  • PIPE, named pipe
  • NET, RFA network special file
  • CDF, context dependent file (used in diskless clusters)
  • LOCKD, the file was locked by another user and its true type could not be determined.
NUMRECS number of logical records (the number of records allocated to the file when it was created). For a DIR file, this indicates the number of directory entries.
RECLEN the logical record size (default is 256 bytes; BDAT files can have user-selected record lengths). For a DIR file, this indicates the size of the directory entry. You cannot specify record length for ASCII or HP-UX files. The record length for HP-UX files is 1.
MODIFIED DATE TIME the day and time when the file was last modified.
PERMISSION specifies who has access rights to the file:
  • R indicates that the file can be read;
  • W indicates that the file can be written;
  • X indicates that the file can be searched (meaningful for directories only).
  • S (HP BASIC only) set-id bit is on, and the search bit is off.
  • s (HP BASIC only) set-id bit is on, and the search bit is on.

There are 3 classes of user permissions for each file:

  • OWNER (left-most 3 characters);
  • GROUP (center 3 characters);
  • OTHER (right-most 3 characters).

See PERMIT for further information.

OWNER specifies the owner identifier for the file (for HP BASIC/WS files, the default owner identifier is always 18). HP BASIC/UX shows the user id of the user that owns the file.
GROUP specifies the group identifier of the file or directory (for HP BASIC/WS, the default group identifier is always 9, which is used for "workstations" such as Series 200/300 BASIC and Pascal). HP BASIC/UX shows the group-id of the group that the file belongs to.

DOS File System Catalogs

The HP Measurement Coprocessor includes the DFS binary, which allows direct access to the PC's DOS file system. The DFS binary provides many of the same features as HFS.

Here is a typical catalog listing of a DOS directory:

DIRECTORY: C:\PROJECTS\PROJECT.ONE

LABEL: HARD_DISK_C

FORMAT: DOS

AVAILABLE SPACE: 66776

FILE NAME FILE TYPE NUM RECS REC LEN       MODIFIED

DATE              TIME

PERMISSION
ASCII_1 ASCII 100 256 15-Apr-91     18:06 RW-RW-RW-
BDAT_1 BDAT 5 256 15-Apr-91    18:10 RW-RW-RW-
MEMOS DIR 0 1 15-Apr-91     14:29 RWXRWXRWX

The first line of the catalog shows the path name of the directory to be cataloged (C:\PROJECTS\PROJECT_ONE in this example).

The second line gives the volume label of the MS-DOS disk.

The third line gives the format of the mass storage medium, which is "DOS" for any DOS volume.

The forth line lists the number of 256-byte sectors on the disk (66776 in this example).

The fifth and sixth lines label the columns of the catalog.

FILE NAME Lists the name of the file. The standard MS-DOS file-name conventions are used (up to eight characters followed by an optional period and an extension of up to three characters).
FILE TYPE Lists the type of the file. DIR specifies a directory. ASCII, BDAT, PROG, and PROG2 specify the standard HP BASIC data and program file types. DOS specifies an "untyped" MS-DOS file.
NUM RECS Lists the number of logical records (the number of records allocated to the file when it was created). For a DIR file, NUM RECS is always 0.
REC LEN The logical record size. The record length is always 256 for an ASCII file, and always 1 for a DOS file. The default record length for a BDAT file is 256, but you can specify a user-defined record length. For a DIR file, REC LEN is always 1.
MODIFIED DATE TIME The date and time when the file was last modified.
PERMISSION Specifies who has access rights to the file: R indicates that the file can be read. W indicates that the file can be written to. X indicates that the file can be searched (meaningful for directories only). There are three classes of user permissions for each file: OWNER (left-most 3 characters). GROUP (center 3 characters). OTHER (right-most 3 characters). By default, the DFS binary sets the permissions for all new files to "RW-RW-RW-" and for all new directories to "RWXRWXRWX". You can use the PERMIT statement to make a file read-only. However, if you change the OWNER bits, the GROUP and OTHER bits will also change. Refer to the PERMIT statement for more details.

CAT of an SRM Directory (not supported on HP BASIC/UX 700)

In order to perform a CAT of an SRM directory or file, you need to have R (read) access capability on the directory to be cataloged, as well as R capability on all superior directories.

The catalog listing format used by the SRM system depends upon the line-width capacity of the device used for display.

When cataloging a remote directory on a 50-column display, the SRM system uses the following catalog format:

USERS/STEVE/PROJECTS/DIR1:REMOTE 21,0

LABEL: Disk1

FORMAT: SDF

AVAILABLE SPACE: 54096
FILE NAME PUB ACC FILE TYPE NUMBER RECORDS RECORD LENGTH OPEN STAT
Common_data MRW ASCII 48 256 OPEN
Personal_data BDAT 33 256 LOCK
Program_alpha RW PROG 44 256
HP9845_DATA R DATA? 22 256
HP9845_STORE MRW PROG? 9 256
Pascal_file.TEXT MRW TEXT 37 256
Program_500 MRW PROG? 12 256

When cataloging an SRM directory on an 80-column display, the system uses the following catalog format:

USERS/STEVE/PROJECTS/DIR1:REMOTE 21,0

LABEL: Disk1

FORMAT: SDF

AVAILABLE SPACE: 54096
FILE NAME LEV SYS TYPE FILE TYPE NUMBER RECORDS RECORD LENGTH MODIFIED DATE      TIME PUB ACC OPEN STAT
Common_data 1 ASCII 48 256 2-Dec-83    13:20 MRW OPEN
Personal_data 1 98X6 BDAT 33 256 2-Dec-83    13:20 LOCK
Program_alpha 1 98X6 PROG 44 256 3-Dec-83    15:06 RW
HP9845_DATA 1 9845 DATA 22 256 10-Oct-83    8:45 R
HP9845_STORE 1 9845 PROG 9 256 10-Oct-83    8:47 MRW
Pascal_file.TEXT 1 PSCL TEXT 37 256 11-Nov-83 12:25 MRW
Program_500 1 9000 PROG 12 256 13-Dec-83    9:54 MRW

The header gives you the following information:

line 1 Directory specifier, including volume specifier. The full path to the specified directory is displayed. Passwords used in the path are not displayed.

If the directory path specifier contains more characters than the display width, the last 49 or 79 characters (depending on catalog format) in the path specifier are shown. An asterisk (*) as the left-most character in the path specifier indicates that leading characters were truncated for the display.

The system remembers a maximum of 160 characters for any directory path specifier at a single time. If a path specifier contains more than 160 characters, the excess characters are removed from the beginning of the specifier and are not retained. This restriction does not affect movement within the directory structure.

line 2 Volume label of the volume containing the directory being cataloged.
line 3 Directory format, such as SDF (Structured Directory Format).
line 4 Number of bytes available on the volume (given in increments of 256 bytes).
lines 5 and 6 Labels for columns of information given for each file. The information provided is summarized below.

Each column of the remaining catalog gives you the following information:

FILE NAME lists the names of the files and directories in the directory being cataloged.
LEV (80-column format only) shows the level of the file relative to the current working directory or specified directory. (The level is always shown as 1 in directory listings for Series 200/300/400 workstations.)
PUB ACC lists the access capabilities available to all SRM system users. The three capabilities are READ, (R) WRITE (W) and MANAGER (M).
  • Public MANAGER capability on a file or directory allows any user on the SRM system to PURGE that file or directory and to modify or add to its passwords (with PROTECT). Password-protected MANAGER capability gives users who supply the required password both READ and WRITE capabilities as well as MANAGER capability.
  • READ capability on a directory allows you to access any file or directory in the directory. The READ capability on a file allows you to read the contents of the file.
  • WRITE capability on a directory allows you to create or delete a file or directory in that directory. The WRITE capability on a file allows you to write information into that file.
SYS TYPE (80-column format only) shows the type of system used to create the file. The system type is not shown for ASCII files and directories. 98X6 denotes a Series 200/300 computer. (If the system does not recognize the system type, a coded identifier, obtained from the system being identified, appears in this column.)
FILE TYPE indicates the file's type. Directories are indicated as type DIR. In the 50-column format, a question mark is appended to the file type if the file was not created on a Series 200/300 computer and was a type other than ASCII or DIR. For example, in the display illustrated earlier, DATA and PROG files created on an HP 9845 are listed as such, but shown with the question mark.

File types recognized by the HP BASIC system on SRM are: ASCII, BDAT, BIN, DIR, HP-UX, PROG, PROG2, and SYSTM, as well as Series 200/300 Pascal and Series 500 file types.

If the system does not recognize a file's type, a coded file type identifier (obtained from the system originating the file) appears in the FILE TYPE column.

NUMBER RECORDS indicates the number of records in the file.
RECORD LENGTH indicates the number of bytes constituting each of the file's records.
MODIFIED (80-column format only) show the date and time the file's contents were last changed.
OPEN STAT shows whether the file is currently open (OPEN), locked (LOCK) or corrupt (CORR). OPEN indicates that the file has been opened, via ASSIGN, by a user. An open file is available for access from other workstations. LOCK means the file is accessible only from the workstation at which the file was locked. CORR indicates that the disk lost power while accessing the file, possibly altering the file's contents. If the entry is blank, the file is closed and available to any user.

NOTE
If a file's status is shown as corrupt (CORR), you should run the DSCK Utility program to check the directory structure and its integrity on the SRM system disk. Refer to the SRM System Administrator's Guide (or SRM Operating System Manual) for details.

CAT of an SRM/UX Directory (not supported on HP BASIC/UX 700)

To perform a CAT of an SRM/UX directory or file, you need R (read) and X (search) permissions on the directory to be cataloged, as well as X (search) permissions on all superior directories.

To perform a CAT of an SRM/UX file, you need R (read) permission on the file to be cataloged, as well as X (search) permissions on all superior directories.

The catalog format used by SRM/UX depends on the line-width capacity of the display device.

On SRM/UX, a catalog of a directory on a 50-column display has the following format:

:REMOTE 21,0

LABEL: BOOT

FORMAT: SRM-UX

AVAILABLE SPACE: 123456789
FILE NAME FILE

TYPE

NUMBER

RECORDS

REC LEN PERMS OP ST
SYSTEMS DIR

11

24

RWXR-XR-X
console CDEV

0

1

RW--W--W-
EDITTEST.TEXT TEXT

8

256

RW-R--R--
AUTOST PROG

2

256

RW-R--R--
srmdpipe PIPE

0

1

RW-------
EST ASCII

1

256

RW-RW-RW- LO
PTESTCAT HP-UX

984

1

RW-RW-R-- 90

On SRM/UX, a catalog of a directory on an 80-column display has the following format:

:REMOTE 21,0

LABEL: BOOT

FORMAT: SRM-UX

AVAILABLE SPACE: 123456789
FILE NAME FILE TYPE NUMBER RECORDS REC LEN       MODIFIED DATE         TIME PERMS OWNER GROUP OPEN STAT
SYSTEMS DIR

11

24

1-Mar-90    16:56 RWXR-XR-X 0 1
console CDEV

0

1

12-Oct-90   17:05 RW--W--W- 0 1
EDITTEST.TEXT TEXT

8

256

12-Dec-89  15:20 RW-R--R-- 175 54
AUTOST PROG

2

256

5-Jan-90     15:07 RW-R--R-- 175 54
srmdpipe PIPE

0

1

12-Oct-90  11:45 RW------- 0 1
PTEST ASCII

1

256

2-Jan-90     10:51 RW-RW-RW- 17 9 LOCK
PTESTCAT HP-UX

984

1

2-Mar-90    15:12 RW-RW-R-- 175 54 OPEN

The header gives you the following information:

line 1 Directory and volume specifier. The full path to the specified directory is displayed.

If the directory path specifier contains more characters than the display width, the last 49 or 79 characters (depending on catalog format) in the path specifier are shown. An asterisk (*) as the left-most character in the path specifier indicates that leading characters were truncated for the display.

line 2 Label of the volume containing the directory being cataloged.
line 3 Directory format.
line 4 Number of bytes available on the volume in 256-byte increments.
lines 5 and 6 Labels for columns of information given for each file.

The columns in the catalog give you the following information:

FILE NAME lists the names of the files and directories in the directory being cataloged.
FILE TYPE indicates the file type. File types recognized by HP BASIC on SRM/UX are the following:
  • DIR - directory
  • PROG - program file
  • PIPE - named pipe

The SRM/UX user can also see the following special HP-UX files in a CAT listing, but cannot manipulate them:

  • NET - network special file
  • SOCK - HP-UX socket
  • BDEV - block special file
  • CDEV - character special file

HP BASIC/WS on SRM/UX also recognizes TEXT and ASCII files.

If the system does not recognize a file type, it prints a numeric code or "OTHER".

NUMBER RECORDS indicates the number of records in a file.
REC LEN indicates the number of bytes in each file record (always 24 for directories (DIR), regardless of actual size).
MODIFIED DATE/TIME (80-column format only) shows the date and time when the file's contents were last changed.
PERMS specifies who has access rights to a file.
  • R - indicates that a file can be read.
  • W - indicates that a file can be written.
  • X - indicates that a directory can be searched (meaningful for directories only).

Three classes of user permissions exist for each file:

  • OWNER - left-most three characters.
  • GROUP - center three characters.
  • OTHER - right-most three characters.

See PERMIT for further information.

OWNER specifies the owner identifier for the file. HP BASIC/WS on SRM/UX shows the user id of the user that owns the file.
GROUP specifies the group identifier of the file or directory. HP BASIC/WS on SRM/UX shows the group id of the group to which the file belongs.
OPEN STAT shows whether the file is currently open (OPEN) or locked (LOCK). OPEN indicates that the file has been opened, via ASSIGN, by a user. An open file is available for access from other workstations. LOCK means the file is accessible only from the workstation at which the file was locked. If the entry is blank, the file is closed and available to any user.

CAT to a Device

When the symbol # is included in a CAT statement, the numeric expression following this symbol must be a device selector. The catalog listing is sent to the device specified by this expression.

CAT to a String Array (Requires MS)

Catalog listings can be sent to a string array. The array must be one-dimensional, and each element of the array must contain at least 80 characters for a directory listing or 45 characters for a PROG-type file listing.

If the directory information does not fill the array, the remaining elements are set to null strings. If the directory information "overflows" the array, the overflow is not reported as an error. When a CAT of a mass storage directory is sent to a string array, the catalog's format is different than when sent to a device. This format is shown below. Protect status is shown by letters, instead of an asterisk. An unprotected file has the entry MRW in the PUB ACC (public access) column. A protected BDAT file has no entry in that column. Other types of protected files show R (read access). In addition to the standard information, this format also shows OPEN in the OPEN STAT column when a file is currently assigned.

:CS80,702,0

VOLUME LABEL: B9836

FORMAT: LIF

AVAILABLE SPACE: 11
FILE NAME SYS TYPE FILE TYPE NUMBER RECORDS RECORD LENGTH MODIFIED DATE TIME PUB ACC OPEN STAT
SYSTEM_BA5 1 98X6 SYSTM 1024 256 29 Nov 86 15:24:55 MRW
AUTOST 1 98X6 PROG 38 256 29 Nov 86 09:25:07 MRW

To aid in accessing the catalog information in a string, the following table gives the location of some important fields in the string.

Field Position (in String)
File Name 1 through 21
File Type 32 through 36
Number of Records 37 through 45
Record Length 46 through 54
Time Stamp 56 through 71
Public Access Capabilities 73 through 75
Open Status 77 through 80

The EXTEND Option (Requires MS)

If EXTEND is specified in a CAT TO String_array$(*) operation, the directory catalog will be in HFS format for an HFS disk, LIF format for a LIF disk, and SRM/UX format for an SRM/UX directory.

With an HFS disk, each element of the array must contain at least 49 characters. If each element has less than 72 characters, the PERMISSION, OWNER, and GROUP are omitted. With a LIF disk, each element of the array must contain at least 47 characters. If each element has less than 65 characters, the DATE and TIME will be omitted. With an SRM or SRM/UX directory, each element of the array must contain at least 80 characters.

NAMES takes precedence over EXTEND if both are given.

Catalogs of PROG-Type Files (Requires MS)

If the file specifier is for a PROG or PROG2 file, the following information is included:

SAMPLE NAME SIZE TYPE
MAIN 692 BASIC
Esc 924 COMPILED UTILITY
FNDummy 166 BASIC
          AVAILABLE ENTRIES= 0

If any binary programs have a version code different from the HP BASIC, both a warning and the version codes of the binary program and HP BASIC system are included with the listing. CAT of a PROG-type file uses the same format, whether the destination is a device or a string.

Using CAT with SKIP (Requires MS)

Including the SELECT option directs the computer to list only the files that begin with or match the value of the specified string expression.

CAT; SELECT "B21"

If the string expression contains more characters than are allowed in a file name (10 for LIF, 14 for HFS, 255 for long file name systems, and 16 for SRM), then only the first 10 characters if LIF, 14 characters if HFS, or 16 characters if SRM are used. If SELECT is not included, all files are sent to the destination (if possible).

Including the SKIP option directs the computer to skip the specified number of (selected) file entries before sending entries to the destination.

  CAT; SKIP 12

If SKIP is not included, no files are skipped.

If an option is given more than once, only the last instance is used.

Using CAT with COUNT (Requires MS)

Including COUNT provides a means of determining the number of lines sent to the destination, plus the number of files skipped, if any.

CAT; COUNT N_files

The variable that follows COUNT receives the sum of the number of selected files plus the number of lines in the catalog header (and trailer for PROG-type files); keep in mind that the number of selected files includes the number of files sent to the destination plus the number of files skipped, if any. Catalogs sent to external devices in the LIF format have a five-line header; in SRM and HFS formats they have seven-line headers. Catalogs to string arrays are SRM format unless EXTEND is added. Catalogs of individual PROG files have a three-line header and a one-line trailer. If an "overflow" of a string array occurs, the count is set to the number of string-array elements plus the number of files skipped. If no entries are sent to the destination (because the directory is empty, or because not entries were selected, or because all selected entries were skipped), the value returned depends on whether there is a header. If there is no header, then zero (0) is returned. If there is a header, then the value returned is the size of the header plus the number following the SKIP option (the number of files to be skipped).

When using WILDCARDS, COUNT receives the sum of the number of files matching the wildcard argument plus the number of lines in the catalog header plus the number of files skipped.

If an option is given more than once, only the last instance is used.

Using the NAMES Option (Requires MS)

Using the NAMES option, as shown in the following statement, will produce a multi-column listing of only the names of the files.

   CAT ; NAMES [Return]

lost+found    WORKSTATIONS    SYSTEM_BA5     MY_PROG       DATA_13

PROJECTS

Executing the following statement:

CAT TO A$(*);NAMES

will put one file name in each array element.

CAT TO string;NAMES in HP BASIC/UX may cause a string overflow if a file name is longer than 14 characters (since longer names are allowed in HP BASIC/UX), and the string array is not large enough to hold the entire name.

Suppressing the Heading (Requires MS)

Including the NO HEADER option directs the computer to omit the directory header (and trailer) that would otherwise be included.

CAT ; NO HEADER

When NO HEADER is specified, the lines of the header (and trailer) are then omitted from the COUNT variable.

When NAMES is specified, there is NO HEADER whether or not NO HEADER is specified.

The PROTECT Option (SRM Only; not supported on HP BASIC/UX700)

PROTECT is a CAT option available only on SRM volumes. This option requires the SRM, DCOMM, and MS binaries. The PROTECT option displays the password(s) and associated access capabilities for the specified file or directory.

For example, the statement:

CAT "Test_file:<MPASS>:REMOTE";PROTECT

might produce the display:

PASSWORD CAPABILITY
================ ==================
MPASS MANAGER,READ,WRITE
WPASS WRITE
RPASS READ
PASSWORD MANAGER

Use of this option requires MANAGER access capability on the file or directory. If the MANAGER capability is public, the PROTECT option may be used by any SRM user.

PROTECT must be specified separately from other CAT options, and is allowed only with SRM files and directories. Note that the PROTECT option is a no-op on SRM/UX. If you use this option on SRM/UX, you will see a header with no passwords listed.

Using PROTECT with media other than SRM returns ERROR 1 Configuration Error.

HP BASIC/DOS Specifics

CAT functions the same as for HP BASIC/WS except that the HFS binary is not included with the measurement coprocessor; it must be purchased separately if desired. The DFS binary provides additional HP BASIC/DOS functionality described earlier in this section.

CAUSE ERROR

Supported On UX WS DOS
Option Required None
Keyboard Executable Yes
Programmable Yes
In an IF ... THEN ... Yes

CAUSE ERROR simulates the occurrence of an error of the specified number.

Example Statements

CAUSE ERROR Err_num
IF Testing THEN CAUSE ERROR 80

Syntax

Item Description Range
error number numeric expression, rounded to an integer 1 through 999; 1001 through 1080

Semantics

When this statement is executed, it initiates the normal error-reporting action taken by the system when an error is encountered in a program line.

If ON ERROR is in effect and CAUSE ERROR is executed in a program line, the appropriate branch is initiated--just as if an actual error occurred on that line. When executed from a running program, CAUSE ERROR affects the error indications ERRN, ERRM$, ERRL, and ERRLN; each is set to the value appropriate for the specified error number and line number. However, ERRDS is not affected.

If CAUSE ERROR is executed at the keyboard, or if executed in a running program (while ON ERROR is not in effect), HP BASIC shows the error number (and error message, if the ERR binary is present) in the system message line of the display. (Note that errors caused by executing statements from the command line do not affect the error indications listed in the preceding paragraph.)

CDIAL

Supported On UX* WS DOS
Option Required KBD
Keyboard Executable Yes
Programmable Yes
In an IF ... THEN ... Yes

CDIAL returns information about "control dial" devices.

Example Statements

CDIAL(1)
IF BIT(CDIAL(0),3) THEN GOSUB Dial3_touched

Syntax

Item Description Range
dial selector numeric expression, rounded to an integer 0 through 15

Semantics

Two different types of results can be returned by this function:

HP BASIC/UX Specifics

Devices to be addressed using CDIAL must not have been opened by the X Windows server. These devices must also be connected to a local system since they cannot be accessed on a remote system. See the section "Opening Input Devices" in the chapter "System-Level Customization" found in the Using the X Window System, Version 11 manual, for details on how to prevent the X Window server from opening specified HIL devices.

CHANGE

Supported On UX WS DOS
Option Required EDIT and PDEV
Keyboard Executable Yes
Programmable No
In an IF ... THEN ... No

CHANGE provides search-and-replace operations for editing programs.

Example Statements

CHANGE "Old Text" TO "New Text"

CHANGE "Row" TO "Column" IN 2560,3310

CHANGE "November" TO "December";ALL

Syntax

Item Description Range
old text literal --
new text literal --
beginning line number integer constant identifying a program line 1 through 32 766 (1 through 2 147 483 646 for HP BASIC/UX 700)
beginning line label name of a program line any valid name
ending line number integer constant identifying a program line 1 through 32 766 (1 through 2 147 483 646 for HP BASIC/UX 700)
ending line label name of a program line any valid name

Semantics

CHANGE finds all occurrences of a specified character sequence and replaces it with another. This occurs whether the character sequence is found in variable names, keywords, literals, or line numbers. Note that if line numbers are changed, unexpected results may occur.

If ALL is specified, all legal changes are made automatically, without additional keyboard interaction. If ALL is not specified, the computer finds each occurrence, tentatively changes old text to new text, and asks you to confirm the change.

[up arrow] and [down arrow] exit CHANGE mode. [EXECUTE] confirms a change, and exits CHANGE mode.

When the specified range is exhausted or the end of the program is reached, the CHANGE command is terminated and the message "old text" not found is displayed.

During the course of a CHANGE, if a syntax error is caused by the altered text, the appropriate error message is displayed. When the line is corrected and entered, the CHANGE command continues.

If a change causes a line to become longer than the maximum length of a line of code, a syntax error is generated, the erroneous change will not take place, and the CHANGE command is aborted. The CHANGE command will also be aborted if a replacement results in the alteration of a line number, although the line whose number was changed now exists in two locations.

If the starting line number does not exist, the next line is used. If the ending line number does not exist, the previous line is used. If a line label doesn't exist, an error occurs and the CHANGE is cancelled.

If there were no occurrences found, the cursor is left at the end of the first line searched. If one or more occurrences were found, the cursor is left at the end of the line containing the last occurrence.

CHANGE is not allowed while a program is running; however, it may be executed while a program is paused. The program is continuable if it has not been altered by pressing [Return] or [Delete line] ([ENTER] or [DEL LN]).

While in the CHANGE mode, keyboard execution of commands is only possible with the [EXECUTE] key on a 98203 keyboard. Using [ENTER] causes an error.

CHECKREAD

Supported On UX WS DOS*
Option Required MS
Keyboard Executable Yes
Programmable Yes
In an IF ... THEN ... Yes

CHECKREAD enables or disables optional read-after-write verification of data sent to mass storage media. Default condition is OFF.

Example Statements

IF Important_data THEN CHECKREAD ON
CHECKREAD OFF

Syntax

Semantics

Executing CHECKREAD ON directs the computer to perform a read-after-write verification of every sector of data sent to mass storage files by any of the following statements (executed in any program context):

COPY        PRINT LABEL       RE-STORE
CREATE        PROTECT       SAVE
CREATE ASCII        PURGE       STORE
CREATE BDAT        RENAME       TRANSFER
OUTPUT        RE-SAVE

If the bit-by-bit comparison does not detect an exact match, an error is reported.

Executing CHECKREAD OFF cancels this optional verification.

Keep in mind that using this feature may increase data reliability, but at the expense of reduced disk-access speed and increased disk wear.

CHECKREAD does not affect PRINTER IS file or PLOTTER IS file.

CHECKREAD of SRM Volumes (not supported on HP BASIC/UX 700)

For SRM, CHECKREAD is implemented as a no-op, because the CHECKREAD function is already performed (by the SRM system) for every HP BASIC operation that reads or writes an SRM file.

CHECKREAD of HFS Volumes with HP BASIC/UX

Because HP BASIC/UX uses the HP-UX operating system file system, buffer cache for all HFS file I/O, it is not possible to verify the data on the physical media. Therefore, CHECKREAD is not appropriate for HFS with HP BASIC/UX.

HP BASIC/DOS Specifics

For HFS, CHECKREAD functions the same as for HP BASIC/WS if the HFS binary has been installed. CHECKREAD is not supported for DFS.

CHGRP

Supported On UX WS DOS
Option Required None
Keyboard Executable Yes
Programmable Yes
In an IF ... THEN ... Yes

CHGRP modifies the group identifier of an HFS or SRM/UX file or directory (for HP-UX compatibility).

Example Statements

CHGRP New_group_id,"/DirPath/HFSfile"
CHGRP 15,"*"
CHGRP 16,"[a-z]?" ! WILDCARDS UX only

Syntax

Item Description Range
group identifier numeric expression, rounded to an integer 0 through 32 767
file or directory specifier string expression specifying a file on an HFS or SRM/UX volume (see drawing)
directory path literal (see MASS STORAGE IS)
HFS directory or file name literal 1 to 14 characters (short file name systems), 1 to 255 characters (long file name systems)
SRM/UX file or directory name literal 1 to 16 characters
volume specifier literal (see MASS STORAGE IS)

Semantics

To execute CHGRP, you must currently own the file or directory. For HFS files and directories, the owner identifier must be 18. SRM/UX users should obtain information about their owner identifier from their system administrator.

If you change the ownership with CHOWN, then you cannot subsequently use CHGRP to change the group identifier of the file.

If no directory path is specified, the current working directory is assumed. If no volume is specified, the current default volume is assumed.

If you are using a version of HP BASIC that supports wildcards, you can use them in file specifiers with CHGRP. You must first enable wildcard recognition using WILDCARDS. Refer to the keyword entry for WILDCARDS for details.

Major Objective: HP-UX Compatibility

This keyword is implemented primarily for compatibility with the HP-UX operating system. Group identifiers allow files and directories to be accessed by all users in the same group, while restricting access to users in all other groups. Therefore, you can use CHGRP to give group permissions to a specific HP-UX group. HP BASIC will no longer have group permissions on the file, but it will retain owner permissions (unless ownership is changed--such as with CHOWN).

For a list of group identifiers used on an HP-UX system, see your HP-UX system administrator. or look at the identifiers listed in the /etc/group file on the HP-UX system. This file could contain the following entry, which defines the relationship between the group named workstation and the group identifier 9.


     workstation: :9:basic,pws 

If this group identifier is currently being used on an HP-UX system that is to share a disk with HP BASIC , then the HP-UX system administrator may need to change the /etc/group file so that HP BASIC is assigned this group identifier. Otherwise, all other HP-UX users with this group identifier will have the current group access permissions to all HP BASIC files and directories.

Note that the Series 200/300 HP BASIC and Pascal operating systems have the same group identifier of 9; however, Pascal has an owner identifier of 17.

For a list of group identifiers used on SRM/UX, see your system administrator or look at the identifiers listed in /etc/srmdconf.

CHOWN

Supported On UX WS DOS
Option Required None
Keyboard Executable Yes
Programmable Yes
In an IF ... THEN ... Yes

CHOWN modifies the owner identifier of an HFS or SRM/UX file or directory (for HP-UX compatibility).

Example Statements

CHOWN Other_owner_id,"/DirPath/HFSfile"
CHOWN 17,"?_*"

Syntax

Item Description Range
owner identifier numeric expression, rounded to an integer 0 through 32 767
file or directory specifier string expression specifying a file on an HFS or SRM/UX volume (see drawing)
directory path literal (see MASS STORAGE IS)
HFS directory or file name literal 1 to 14 characters (see Glossary)
SRM/UX file or directory name literal 1 to 16 characters
volume specifier literal (see MASS STORAGE IS)

Semantics

To execute CHOWN, you must currently own the file or directory. That is, the owner id of the file must match your user-id. HP BASIC/UX user-ids can be found in the file /etc/passwd. For HFS files and directories on HP BASIC/WS , the user-id is always 18. SRM/UX users should obtain information about owner identifiers from their system administrator or look at the owner identifiers listed in /etc/srmdconf.

If you change the ownership with CHOWN, then you cannot subsequently use CHOWN to change the owner identifier of the file or directory.

If no directory path is specified, the current working directory is assumed. If no volume is specified, the current default volume is assumed.

If you are using a version of HP BASIC that supports wildcards, you can use them in file specifiers with CHOWN. You must first enable wildcard recognition using WILDCARDS. Refer to the keyword entry for WILDCARDS for details.

Major Objective: HP-UX Compatibility

This keyword is implemented primarily for compatibility with the HP-UX operating system. Owner identifiers allow files and directories to have certain access permissions only available to the owner, while restricting access to all other users. Therefore, CHOWN can be used to give an HP-UX user the owner permissions of files and directories. The user, however, will still have group permissions of the file (unless the group identifier is changed--such as with CHGRP).

For a list of the owner identifiers used on an HP-UX system, see your HP-UX system administrator or look at the identifiers listed in the /etc/passwd file on the HP-UX system. It could contain the following entry, which defines the relationship between the owner named basic and the owner identifier 18:

basic:*:18:9:#BASIC workstation user:/WORKSTATIONS:/bin/false

If this owner identifier is currently being used on an HP-UX system that is to share a disk with HP BASIC , then the HP-UX system administrator will need to change the /etc/passwd file so that HP BASIC is assigned this owner identifier. Otherwise, any HP-UX user with this owner identifier will have the current owner access permissions to all HP BASIC files and directories.

Note that the Series 200/300 Pascal system has an owner identifier of 17; however, HP BASIC and Pascal operating systems have the same group identifier of 9.

CHR$

Supported On UX WS DOS IN
Option Required None
Keyboard Executable Yes
Programmable Yes
In an IF ... THEN ... Yes

CHR$ converts a numeric expression into an ASCII character.

Example Statements

Lowercase$=CHR$(NUM(Uppercase$)=32)
A$[Marker;1]=CHR$(Digit=128)
Esc$=CHR$(27)
Kanji$=CHR$(129)& CHR$(64) 

Syntax

Item Description Range
argument numeric expression, rounded to an integer 0 through 255

Semantics

The low order byte of the 16-bit integer representation of the argument is used; the high order byte is ignored. A table of ASCII characters and their decimal equivalent values may be found in the back of this book.

Two-Byte Language Specifics

Certain localized versions of BASIC, such as Japanese localized BASIC, support two-byte characters. You can use CHR$ to build two-byte characters byte-by-byte. For example, the two-byte Roman letter A is CHR$(130)&CHR$(96) (using the Japanese LANGUAGE binary). For more information about two-byte characters, refer to the globalization chapters of the HP BASIC Porting and Globalization manual.

CHRX

Supported On UX WS DOS
Option Required CRTX
Keyboard Executable Yes
Programmable Yes
In an IF ... THEN ... Yes

CHRX returns the number of columns (width) of a character cell (on bit-mapped alpha/graphics displays) or 0 (on displays with non-bit-mapped alpha displays).

Example Statements

CHRX
ALLOCATE INTEGER Char_cell(1:CHRY,1:CHRX)

Syntax

Semantics

Character cells are 20 (rows) by 10 (columns) for 1280 × 1024 resolution bit-mapped alpha displays, 16 (rows) by 8 (columns) for 1024 × 768 resolution bit-mapped alpha displays, 16 (rows) by 8 (columns) for 640 by 480 resolution bit-mapped displays, 15 (rows) by 12 (columns) for medium-resolution bit-mapped alpha displays, and 14 (rows) by 8 (columns) for DOS displays.

If the alpha display is not bit-mapped (that is, if the alpha is separate from the graphics raster, and is generated by character-generator-ROM hardware), then this function returns 0.

Two-Byte Language Specifics

Certain localized versions of HP BASIC , such as Japanese localized HP BASIC , support two-byte characters. Display systems operating in globalized (two-byte) mode use different character cell sizes depending upon the localized font. For more information about two-byte characters, refer to the globalization chapters of the HP BASIC Porting and Globalization manual.

CHRY

Supported On UX WS DOS
Option Required CRTX
Keyboard Executable Yes
Programmable Yes
In an IF ... THEN ... Yes

CHRY returns the number of rows (height) of a character cell (on bit-mapped alpha/graphics displays) or 0 (on displays with non-bit-mapped alpha displays).

Example Statements

CHRY
ALLOCATE INTEGER Char_cell(1:CHRY,1:CHRX)

Syntax

Semantics

Character cells are 20 (rows) by 10 (columns) for 1280 × 1024 resolution bit-mapped alpha displays,16 (rows) by 8 (columns) for 1024 × 768 resolution bit-mapped alpha displays, 16 (rows) by 8 (columns) for 640 by 480 resolution bit-mapped displays, 15 (rows) by 12 (columns) for medium-resolution bit-mapped alpha displays, and 14 (rows) by 8 (columns) for DOS displays.

If the alpha display is not bit-mapped (that is, if the alpha is separate from the graphics raster, and is generated by character-generator-ROM hardware), then this function returns 0.

Two-Byte Language Specifics

Certain localized versions of HP BASIC , such as Japanese localized HP BASIC , support two-byte characters. Display systems operating in globalized (two-byte) mode use different character cell sizes depending upon the localized font. For more information about two-byte characters, refer to the globalization chapters of the HP BASIC Porting and Globalization manual.

CLEAR

Supported On UX WS DOS IN
Option Required IO
Keyboard Executable Yes
Programmable Yes
In an IF ... THEN ... Yes

CLEAR clears the specified HP-IB or Data Communications interfaces.

Example Statements

CLEAR 7
CLEAR Voltmeter
CLEAR @Source

Syntax

Item Description Range
I/O path name name assigned to a device or devices any valid name (see ASSIGN)
device selector numeric expression, rounded to an integer (see Glossary)

Semantics

HP-IB Interfaces

CLEAR places all or only selected HP-IB devices into a pre-defined, device-dependent state. The computer must be the active controller to execute this statement. The bus messages sent are the same whether or not the computer is the system controller. When primary addresses are specified, the bus is reconfigured and the SDC (Selected Device Clear) message is sent to all devices which are addressed by the LAG message.

Summary of CLEAR Bus Actions
Interface Select Code Only Primary Address Specified
ATN

DCL

ATN

MTA

UNL

LAG

SDC

Data Communications Interfaces

CLEAR may also be directed to a Data Communications interface. The result is to clear the interface buffers; if the interface is suspended, a disconnect is also executed.

CLEAR ERROR

Supported On UX WS DOS IN*
Option Required None
Keyboard Executable No
Programmable Yes
In an IF ... THEN ... Yes

CLEAR ERROR resets error indicators (ERRN, ERRM$, ERRL, and ERRLN) to their power-up values.

Example Statements

CLEAR ERROR
IF Done THEN CLEAR ERROR

Syntax

Semantics

CLEAR ERROR affects the following error indications:

CLEAR LINE

Supported On UX WS DOS
Option Required CRTX
Keyboard Executable Yes
Programmable Yes
In an IF ... THEN ... Yes

CLEAR LINE clears the keyboard input line. It has the same effect as pressing [Shift]-[Clear line] ([CLR LN] on a 98203 keyboard).

Example Statements

CLEAR LINE
IF Flag THEN CLEAR LINE

Syntax

CLEAR SCREEN (or CLS)

Supported On UX WS DOS IN
Option Required CRTX
Keyboard Executable Yes
Programmable Yes
In an IF ... THEN ... Yes

CLEAR SCREEN clears the contents of the alpha display.

Example Statements

CLS
CLEAR SCREEN
IF Loop_count=1 THEN CLEAR SCREEN

Syntax

Semantics

CLEAR SCREEN clears the alpha display area and the associated memory. It has the same effect as executing OUTPUT KBD;CHR$(255)&"K"; or pressing the [Clear display] ([CLR SCR]) key.

CLEAR WINDOW

Supported On UX WS* DOS*
Option Required RMBUX
Keyboard Executable Yes
Programmable Yes
In an IF ... THEN ... Yes

CLEAR WINDOW clears the contents of the specified window.

Example Statements

CLEAR WINDOW Fred
CLEAR WINDOW 604

Syntax

Item Description Range
window number numeric expression, rounded to integer 600 through 699

Semantics

CLEAR WINDOW is only valid when running HP BASIC/UX under X Windows. The window number must correspond to a window created with the CREATE WINDOW statement, or root HP BASIC window (number 600). This statement then clears the specified window.

When not in a window system, this statement will cause an error. Note, there are three ways to clear the root HP BASIC window:


  CLS 
  CLEAR SCREEN 
  CLEAR WINDOW 600

CLIP

Supported On UX WS DOS
Option Required GRAPH
Keyboard Executable Yes
Programmable Yes
In an IF ... THEN ... Yes

CLIP defines, enables, or disables the soft clip limits for subsequent graphics output.

Example Statements

CLIP Left,Right,Bottom,Top
CLIP ON
CLIP OFF

Syntax

Item Description Range
left edge numeric expression in current units --
right edge numeric expression in current units greater than left edge
bottom edge numeric expression in current units --
top edge numeric expression in current units greater than bottom edge

Semantics

Executing CLIP with numeric parameters allows the soft clip area to be set to the specified soft clip limits. If CLIP is not executed, the area most recently defined by either VIEWPORT or the PLOTTER IS statement is the clipping area. All plotted points, lines, or labels are clipped at this boundary.

The hard clip area is specified by the PLOTTER IS statement. The soft clip area is specified by the VIEWPORT and CLIP statements. CLIP ON sets the soft clip boundaries to the last specified CLIP or VIEWPORT boundaries, or to the hard clip boundaries if no CLIP or VIEWPORT has been executed. CLIP OFF sets the soft clip boundaries to the hard clip limits.

CLS

CLS is identical to CLEAR SCREEN.

CMD

See SEND.

CMPLX

Supported On UX WS DOS
Option Required COMPLEX
Keyboard Executable Yes
Programmable Yes
In an IF ... THEN ... Yes

CMPLX creates a complex number with the first argument representing the real part and the second argument representing the imaginary part. The arguments given may be REAL, INTEGER, or COMPLEX variables.

Example Statements

C=CMPLX(-2,1)
Result=CMPLX(-2,356,.0012)
Complex_value=CMPLX(Real_part,Imaginary_part)

Syntax

Item Description/Default Range\Restrictions
argument numeric expression any valid INTEGER, REAL, or COMPLEX expression

Semantics

Arguments used by CMPLX are converted to two 8-byte (64-bit) floating-point values and handled accordingly. If arguments are COMPLEX, then only the real part of that COMPLEX argument is used.

COLOR

COLOR is a secondary keyword for the following primary keywords:

COM

Supported On UX WS DOS IN*
Option Required None
Keyboard Executable No
Programmable Yes
In an IF ... THEN ... No

COM dimensions and reserves memory for variables in a special "common" memory area so more than one program context can access the variables.

Example Statements

COM X,Y,Z
COM /Block/ Text$,@Path,INTEGER Points(*)
COM INTEGER I,J,REAL Array(-128:127)
COM Buffy$[1024] BUFFER
COM COMPLEX Complex_num

Item Description Range
block name name identifying a labeled COM area any valid name
numeric name name of a numeric variable any valid name
string name name of a string variable any valid name
lower bound integer constant; Default=OPTION BASE value (0 or 1) -32 767 through +32 767 (see "array" in Glossary)
upper bound integer constant -32 767 through +32 767 (see "array" in Glossary)
string length integer constant 1 through 32 767
I/O path name name assigned to a device, devices, mass storage file, or buffer any valid name (see ASSIGN)

Semantics

Storage for COM is allocated at prerun time in an area of memory which is separate from the data storage used for program contexts. This reserved portion of memory remains allocated until SCRATCH A, SCRATCH BIN, or SCRATCH C is executed.

Changing the definition of the COM space is accomplished by a full program prerun. This can be done by:

When COM allocation is performed at prerun, the new program's COM area is compared to the COM area currently in memory. When comparing the old and new areas, HP BASIC looks first at the types and structures declared in the COM statements. If the "text" indicates that there is no way the areas could match, then those areas are considered mismatched. If the declarations are consistent, but the shape of an array in memory does not match the shape in a new COM declaration, HP BASIC takes the effect of REDIM into account. If the COM areas could be matched by a REDIM, they are considered to be in agreement. When this happens, the treatment of the arrays in memory depends upon the program state. If the COM matching occurred because of a programmed LOADSUB, the arrays in memory keep their current shape. If the COM matching occurred for any other reason (such as RUN or programmed LOAD), the arrays in memory are redimensioned to match the declarations. Any variable values are left intact. All other COM areas are rendered undefined, and their storage area is not recovered by HP BASIC . New COM variables are initialized at prerun: numeric variables to 0, string variables to the null string.

Each context may have as many COM statements as needed (within the limits stated below), and COM statements may be interspersed between other statements. If there is an OPTION BASE statement in the context, it must appear before COM statement. COM variables do not have to have the same names in different contexts. Formal parameters of subprograms are not allowed in COM statements. A COM mismatch between contexts causes an error.

The total number of COM elements is limited to a maximum memory usage of 16 777 215 bytes (or limited by the amount of available memory, whichever is less).

If a COM area requires more than one statement to describe its contents, COM statements defining that block may not be intermixed with COM statements defining other COM areas.

Numeric variables in a COM list can have their type specified as either REAL, INTEGER, or COMPLEX. Specifying a variable type implies that all variables which follow in the list are of the same type. The type remains in effect until another type is specified. String variables and I/O path names are considered a type of variable and change the specified type. Numeric variables are assumed to be REAL unless their type has been specified otherwise.

COM statements (blank or labeled) in different contexts which refer to an array or string must specify it to be of the same size and shape. The lowest-numbered COM satement containing an array or string name must explicitly specify the subscript bounds and/or string length. Subsequent COM statements can reference a string by name only or an array only by using an asterisk specifier (*).

No array can have more than six dimensions. The lower bound value must be less than or equal to the upper bound value. The default lower bound is specified by the OPTION BASE statement.

Any LOADSUB which attempts to define or change COM areas while a program is running generates error 145.

Unlabeled or Blank COM

Blank COM does not contain a block name in its declaration. Blank COM (if it is used) must be created in a main context. The main program can contain any number of blank COM statements (limited only by available memory). Blank COM areas can be accessed by subprograms, if the COM statements in the subprograms agree in type and shape with the main program COM statements.

Labeled COM

Labeled COM contains a name for the COM area in its declaration. Memory is allocated for labeled COM at prerun time according to the lowest-numbered occurrence of the labeled COM statement. Each context which contains a labeled COM statement with the same label refers to the same labeled COM block.

Declaring Buffers

To declare COM variables to be buffers, each variable's name must be followed by the keyword BUFFER; the designation BUFFER applies only to the variable which it follows. String arrays cannot be declared to be buffers.

COMPILE

COMPILE compiles all or part of a program currently in memory for those versions of HP BASIC that support this command. (Not supported on HP BASIC/UX 700.)

Example Statements

COMPILE
COMPILE Sub1 TO Sub2:BEST
COMPILE #701;-Sub1,Sub9:BEST, MTP OFF

COMPLEX

Supported On UX WS DOS
Option Required COMPLEX
Keyboard Executable No
Programmable Yes
In an IF ... THEN ... No

COMPLEX declares complex variables and arrays and reserves storage for them. (For information about COMPLEX as a secondary keyword, see the ALLOCATE, COM, DEF FN, or SUB statements.)

Example Statements

COMPLEX X,Y,Z
COMPLEX Array(-23:2,26)
COMPLEX A(512) BUFFER

Syntax

Item Description/Default Range\Restrictions
numeric name name of a numeric variable any valid name
lower bound integer constant;Default = OPTION BASE value (0 or 1) -32 767 through +32 767 (see "array" in Glossary)
upper bound integer constant -32 767 through +32 767 (see "array" in Glossary)

Semantics

Each COMPLEX variable or array element consists of two floating-point values, one for the real part and one for the imaginary part of the COMPLEX number. Each complex value requires sixteen bytes of storage. The maximum number of subscripts in an array is six, and no dimension may have more than 32 767 elements.

The total number of COMPLEX elements is limited by the fact that the maximum memory usage for all variables--COMPLEX, INTEGER, REAL, and string--within any context is 224-1, or 16 777 215, bytes (or limited by the amount of available memory, whichever is less).

Declaring Buffers

To declare COMPLEX variables to be buffers, each variable's name must be followed by the keyword BUFFER; the designation BUFFER applies only to the variable which it follows.

CONJG

Supported On UX WS DOS
Option Required COMPLEX
Keyboard Executable Yes
Programmable Yes
In an IF ... THEN ... Yes

CONJG returns the complex conjugate of a COMPLEX number.

Example Statements

X=CONJG(Complex_expr)
Result=CONJG(CMPLX(2.1,-8))

Syntax

Item Description/Default Range\Restrictions
argument numeric expression any valid INTEGER, REAL, or COMPLEX value

Semantics

The complex conjugate of a COMPLEX number CMPLX(X,Y) is CMPLX(X,-Y). That is, the imaginary part of the argument is negated. An INTEGER or REAL argument is returned unchanged.

CONT

Supported On UX WS DOS IN
Option Required None
Keyboard Executable Yes
Programmable No
In an IF ... THEN ... No

CONT resumes execution of a paused program at the specified line. If no line is specified, execution resumes at the next line that would have executed if the program had not PAUSEd.

Example Statements


  CONT
  
  CONT 550
  
  CONT Sort

Syntax

Item Description Range
line number integer constant identifying a program line; Default = next program line 1 through 32 766 (1 through 2 147 483 646 for HP BASIC/UX 700)
line label name identifying a program line any valid name

Semantics

CONT can be executed by pressing [CONTINUE] ([f2] in the System menu of an ITF keyboard), or by executing a CONT command. Variables retain their current values whenever CONT executes. CONT causes the program to resume execution at the next statement which would have occurred unless a line is specified.

When a line label is specified, program execution resumes at the specified line, provided that the line is in either the main program or the current subprogram. If a line number is specified, program execution resumes at the specified line, provided that the line is in the current program context. If there is no line in the current context with the specified line number, program execution resumes at the next higher-numbered line. If the specified line label does not exist in the proper context, an error results.

CONTROL

Supported On UX WS DOS
Option Required None
Keyboard Executable Yes
Programmable Yes
In an IF ... THEN ... Yes

CONTROL sends control information an interface register or the internal table associated with an I/O path name. (CONTROL is also used in PASS CONTROL.)

Example Statements

CONTROL @Rand_file,7;File_length  ! Write to a file
CONTROL 1;Row,Column
CONTROL Interface,Register;Value  ! Write to hardware interface
CONTROL @Serial,3;9600      ! Set serial interface baud rate

Syntax

Item Description Range
interface select code numeric expression, rounded to an integer 1 through 32 (interface-dependent)
I/O path name name assigned to a device, devices, mass storage file, buffer, or pipe any valid name (see ASSIGN)
register number numeric expression, rounded to an integer; Default = 0 interface-dependent
control word numeric expression, rounded to an integer -231 through 231-1 (interface-dependent)

Writing to File I/O Paths

I/O path names assigned to files have an association table that can be accessed as a set of registers.

CONTROL writes to this table, starting with the specified register and continuing in turn through the remaining registers until all control words are used. The number of control words must not exceed the number of registers available.

Register assignments can be found in the "Interface Registers" section at the back of this book.

Writing to Hardware Interfaces

Control words are written to the interface registers, starting with the specified register number, and continuing in turn through the remaining registers until all the control words are used. The number of control words must not exceed the number of registers available.

Register assignments can be found in the "Interface Registers" section at the back of this book.

There is a shorthand method available that permits you to assign values to several attributes without naming them individually in the CONTROL statement. You fill a string array with attribute names and a corresponding string or numeric array with attribute values. Then, when you supply the array names to the CONTROL statement, the attribute named in each element of the attribute array will be assigned the corresponding value in the value array. Elements of the attribute array that contain nothing, or nothing but blanks, will be ignored. Only scalar attributes may be assigned values with this shorthand method.

CONVERT

See ASSIGN.

COPY

Supported On UX WS DOS IN*
Option Required None
Keyboard Executable Yes
Programmable Yes
In an IF ... THEN ... Yes

COPY copies individual files or entire disks. When an entire disk is copied, all old files on the destination disk are destroyed.

Example Statements

COPY "OLD_FILE" TO "New_file"
COPY "new" TO "archive";PURGE
COPY ":,700" TO ":,700,1"
COPY ":,4,1" TO ":,4,0"
COPY "/Dir_1/File_1" TO "Dir_3/File_1"
COPY Dir_path$& File$& Vol$ TO "File:,700" 
COPY "File:INTERNAL" TO "File:REMOTE 21,0"
COPY "DIR/*" TO "New_dir";PURGE
COPY "Dir/*" TO "New_dir"
COPY "Type_[a-z]" TO "Dir" ! WILDCARDS UX only
COPY "File?" TO "archive"
COPY "*" TO ":,700,1"

Item Description Range
file specifier string expression (see drawing)
volume specifier string expression (see MASS STORAGE IS)
directory path literal (see MASS STORAGE IS)
file name literal depends on volume's format (see Glossary)
LIF protect code literal; first two non-blank characters are significant > not allowed
SRM password literal; first 16 non-blank characters are significant > not allowed
volume specifier string expression (see MASS STORAGE IS)

Semantics

The contents of the old file are copied into the new file, and a directory entry is created. A protect code (for LIF files) may be specified for the new file, to prevent accidental erasure, etc. COPY will not replace existing files unless you specify the PURGE option.

An error is returned if there is not enough room on the destination device, or if the new file name already exists in the destination directory and the PURGE option is not specified.

If the mass storage volume specifier (msvs) is omitted from a file specifier, the MASS STORAGE IS device is assumed.

If the directory path is also omitted, the MASS STORAGE IS directory is assumed.

Using Wildcards with COPY

If you are using a version of HP BASIC that supports wildcards, you can use them in file specifiers with COPY. You must first enable wildcard recognition using WILDCARDS. Refer to the keyword entry for WILDCARDS for more details.

You may use wildcards in both the source and destination of the COPY. If the wildcard specification for the source matches more than one file, then the destination must be a directory or a LIF volume specifier.

Note that BASIC handles the command

COPY "file_name" TO "dir_name"

in a different manner when wildcards are enabled than when they are disabled.

When wildcards are enabled, BASIC lets you to copy a file to a directory. It interprets the above command as make a copy of file_name and place that copy in a directory called dir_name.

When wildcards are disabled, BASIC interprets the above command as make a copy of file_name and place it in the file called dir_name. If a file or a directory already exists which uses the name dir_name, BASIC generates error 54, Duplicate file name.

Using the PURGE Option

The PURGE option allows the COPY command to replace existing files.

HP BASIC interprets the command COPY "file1" TO "file2"; PURGE as copy the file file1 to file2, replacing file2 if it exists.

HP BASIC interprets the command

COPY "file_name" TO "dir_name"; PURGE

in different ways depending on whether wildcards are enabled or disabled.

When wildcards are enabled, the preceding statement copies file_name into the directory dir_name. If a file with the name file_name already exists in that directory, COPY will replace it.

When wildcards are disabled, HP BASIC replaces the directory identified by dir_name with the file specified by file_name. This works only if dir_name is empty.

Copying an Entire LIF or HFS Volume

LIF and HFS volumes can be duplicated if the destination volume is as large as, or larger than, the source volume. COPY from a larger capacity volume to a smaller capacity volume is only possible when the amount of data on the larger will fit on the smaller. The directory and any files on the destination volume are destroyed. The directory size on the destination volume becomes the same size as that on the source media. When copying an entire volume, the volume specifiers must be unique. File names are not allowed. Disk-to-disk copy time is dependent on media type and interleave factors.

Also note that you will be prompted to continue when executing a volume copy from the keyboard, thus providing safe volume copying. There is no continue prompt when executing volume copy from a program.

HP BASIC/UX supports copying only of LIF volumes, not HFS volumes.

HFS Permissions

With HFS, COPY allows copying of individual files and volumes. HFS directories cannot be copied.

In order to COPY a file on an HFS volume, you need to have R (read) permission on the source file, as well as X (search) permission on the parent directory and all other superior directories. In addition, you will need W (write) and X (search) permission on the destination file's parent directory, as well as X (search) permission on all other superior directories.

HFS File Headers

When copying a file from LIF or SRM to HFS, a special header is added to the beginning of that file. This action is taken because that is the only way to "type" files (which would otherwise be "typeless"). When copying a file from HFS to LIF or SRM volumes, this file header is removed (since these volumes have typed files). Note that HP BASIC handles the file headers automatically and requires no special treatment in programs that use these files.

When copying a SYSTM file from LIF volumes to HFS volumes, it will be given a header and will remain a SYSTM file. However, it will not be bootable. Conversely, copying a bootable HP-UX file from HFS to LIF or SRM will result in an HP-UX file that is not bootable. (STORE SYSTEM will copy the current HP BASIC system from memory onto an HFS volume only in the root directory. STORE SYSTEM will error if the HFS directory is not the root directory (/). If the destination file is in the HFS volume's root directory, it will be a bootable system.)

SRM Passwords (not supported on HP BASIC/UX 700)

With SRM, COPY allows copying of individual files. SRM directories and volumes cannot be copied.

In order to COPY an SRM file, you need to have R (read) access capability on the file, on the parent directory, and on all other superior directories. You must also have W (write) access capability on the destination directory, as well as R access capability on all superior directories.

Although you may include a password in the new file specifier, the system ignores the password. If you wish to protect access to the new file, you must assign the password with PROTECT.

COPYLINES

Supported On UX WS DOS
Option Required EDIT and PDEV
Keyboard Executable Yes
Programmable No
In an IF ... THEN ... No

COPYLINES copies one or more contiguous program lines from one location to another while editing a program.

Example Statements


  COPYLINES 1200 TO 3255
  COPYLINES 10,120 TO 500
  COPYLINES Label1,Label2 TO Label3

Syntax

Item Description Range
beginning line number integer constant identifying program line 1 to 32 766 (1 through 2 147 483 646 for HP BASIC/UX 700)
beginning line label name of a program line any valid name
ending line number integer constant identifying program line 1 to 32 766 (1 through 2 147 483 646 for HP BASIC/UX 700)
ending line label name of a program line any valid name
target line number integer constant identifying program line 1 to 32 766 (1 through 2 147 483 646 for HP BASIC/UX 700)
target line label name of a program line any valid name

Semantics

If the beginning line identifier is not specified, only one line is copied.

The target line identifier will be the line number of the first line of the copied program segment. Copied lines are renumbered if necessary. Any lines which are "pushed down" to make room for the copied lines are renumbered as necessary.

Line number references to the copied code are updated as they would be using REN, with these exceptions: line number references in lines not being copied remain linked to the source lines rather than being renumbered; references to non-existent lines are renumbered as if the lines existed.

If there are any DEF FN or SUB statements in the copied code, the target line number must be greater than any existing line number.

If you try to copy a program segment to a line number contained in the segment, an error will be reported and no copying will occur.

If the starting line number does not exist, the next line is used. If the ending line number does not exist, the previous line is used. If a line label doesn't exist, an error occurs and no copying occurs.

If an error occurs during a COPYLINES (for example, a memory overflow), the copy is terminated and the program is left partially modified.

COS

Supported On UX WS DOS IN
Option Required None
Keyboard Executable Yes
Programmable Yes
In an IF ... THEN ... Yes

COS returns the cosine of the specified angle.

Example Statements

Cosine=COS(Angle)
PRINT COS(X=45)

Syntax

Item Description/Default Range\Restrictions
argument numeric expression in current units of angle when INTEGER or REAL argument

numeric expression in radians when COMPLEX argument

absolute values less than 1.708 312 772 2 E+10 deg. or 2.981 568 244 292 04 E+8 rad. for INTEGER and REAL arguments; see Range Restriction Specifics for COMPLEX arguments and underflow conditions

Semantics

The angle mode set by RAD or DEG determines whether the angle is interpreted in degrees or radians. The angle mode is radians unless you specify degrees using the DEG statement.

If the angle is REAL or INTEGER, the value returned is REAL. If the angle is COMPLEX, the value returned is COMPLEX. To compute the COS of a COMPLEX value, the COMPLEX binary must be loaded.

Range Restriction Specifics

The formula used for computing the COS of a COMPLEX argument is:

CMPLX(COS(Real)*COSH(Imag),-SIN(Real)*SINH(Imag))

where Real is the real part the COMPLEX argument and Imag is the imaginary part of the COMPLEX argument. Some values of a COMPLEX argument may cause errors in this computation. For example,

COS(CMPLX(0,MAXREAL))

will cause error 22 (error 21 in HP BASIC/UX 700) due to the COSH(Imag) calculation.

Note that any COMPLEX function whose definition includes a sine or cosine function will be evaluated in the radian mode regardless of the current angle mode (i.e. RAD or DEG).

The following range restrictions apply in HP BASIC/UX 700 when underflow mode (CONTROL 32,7;mode) is set to Error or Ignore.

Range Underflow Mode\Error Underflow Mode\Ignore
Positive Maximum +1.34217728000000E+008 +1.34217728000000E+008
Negative Minimum -1.34217728000000E+008 -1.34217728000000E+008
Positive Minimum +1.02907134889717E-076 +4.94065645841247E-3241
Negative Maximum -1.02907134889717E-076 -4.94065645841247E-3242

1 An underflow in Ignore mode results in a denormalized number that is less than the value for +MINREAL.

2An underflow in Ignore mode results in a denormalized number that is greater than the value for -MINREAL.

COSH

Supported On UX WS DOS
Option Required COMPLEX
Keyboard Executable Yes
Programmable Yes
In an IF ... THEN ... Yes

COSH returns the hyperbolic cosine of a numeric expression.

Example Statements

Result=COSH(10.3499)
PRINT "Hyperbolic Cosine = ";COSH(Expression)

Syntax

Item Description/Default Range\Restrictions
argument numeric expression -710 through 710 for INTEGER or REAL arguments; see Range Restriction Specifics for COMPLEX arguments and underflow conditions

Semantics

If an INTEGER or REAL argument is given, this function returns a REAL value. If a COMPLEX argument is given, this function returns a COMPLEX value.

Range Restriction Specifics

The formula used for computing COSH is as follows:

(EXP(Argument)+EXP(-Argument))/2

where Argument is the argument of the COSH function.

Some arguments may cause errors in intermediate values computed during this computation. For example,

COSH(MAXREAL)

will cause error 22 (error 21 in HP BASIC/UX 700) due to the EXP(MAXREAL) computation.

The following range restrictions apply in HP BASIC/UX 700 when underflow mode (CONTROL 32,7;mode) is set to Error or Ignore.

Range Underflow Mode\Error Underflow Mode\Ignore
Positive Maximum +7.10475860073944E+002 +7.10475860073944E+002
Negative Minimum -7.10475860073944E+002 -7.10475860073944E+002
Positive Minimum +2.10953732297368E-154 +4.94065645841247E-3241
Negative Maximum -2.10953732297368E-154 -4.94065645841247E-3242

1An underflow in Ignore mode results in a denormalized number that is less than the value for +MINREAL.

2An underflow in Ignore mode results in a denormalized number that is greater than the value for -MINREAL.

COUNT

COUNT is a secondary keyword for these keywords:

CREATE

Supported On UX WS DOS* IN*
Option Required HFS
Keyboard Executable Yes
Programmable Yes
In an IF ... THEN ... Yes

CREATE creates a DOS or HP-UX file. On DOS file systems, CREATE creates a DOS file; on all other file systems, CREATE creates an HP-UX file.

Example Statements

CREATE File_spec$,N_records
CREATE "My_file",12

Syntax

Item Description Range
file specifier string expression (see drawing)
directory path literal (see MASS STORAGE IS)
file name literal depends on volume's format (see Glossary)
LIF protect code literal; first two non-blank characters are significant > not allowed
SRM password literal; first 16 non-blank characters are significant > not allowed
volume specifier literal (see MASS STORAGE IS)
number of records numeric expression, rounded to an integer 1 through 231 - 1

Semantics

CREATE creates a new file of type HP-UX on the default or specified volume or hierarchical directory. A corresponding directory entry is also made. The name of the newly created file must be unique within its directory. CREATE does not open the file; that is performed by ASSIGN. In the event of an error, no directory entry is made and the file is not created.

The number of records parameter specifies how many logical records are to be initially allocated to the file. The logical record size is always 1 for HP-UX files. On LIF volumes, the number of records allocated for the file is fixed; however, on HFS and SRM volumes, files are extensible. See the following section for details about extensible files.

The data representation used in the file depends on the FORMAT option used in the ASSIGN statement used to open the file. See ASSIGN for details.

Extensible Files

Files created with CREATE are "extensible". This means that the file system automatically allocates additional space for the file as new data is written to it. With HFS volumes, the initial size of the file is 0, but the file will automatically be extended as many bytes as necessary whenever an OUTPUT operation would otherwise overflow the file. On SRM volumes, the "number of records" parameter determines the "extent size" of the file (that is, the amount of space automatically appended to the file whenever it is extended). "Preallocating" an extensible file (initially creating a file of sufficient size) will improve the data transfer rate because the file system will not have to extend the file during data transfer operations.

LIF Protect Codes

A protect code is not allowed on an HP-UX file.

HFS Permissions

In order to create a file on an HFS volume, you need to have W (write) and X (search) permission of the immediately superior directory, as well as X (search) permission on all other superior directories.

When a file is created on an HFS volume, access permission bits are set to RW-RW-RW-. (You can modify them with PERMIT, if desired.) HP BASIC/UX permissions may be altered by the user's umask. See the HP-UX Reference, umask(1) entry, for more information.

SRM Access Capabilities (not supported in HP BASIC/UX 700)

In order to CREATE an HP-UX file in an SRM directory, you need to have READ and WRITE capabilities on the immediately superior directory, as well as READ capabilities on all other superior directories.

When a file is created on an SRM volume, all access capabilities are public. Including an SRM password in the file specifier does not protect the file. You must use PROTECT to assign a password. You will not receive an error message for including a password, but a password in the CREATE statement is ignored.

HP BASIC/DOS Specifics

For the LIF and HFS (if present) file systems, CREATE works the same as for HP BASIC/WS. For the DFS file system, CREATE creates a DOS type file rather than an HP-UX file.

CREATE ASCII

Supported On UX WS DOS IN
Option Required None
Keyboard Executable Yes
Programmable Yes
In an IF ... THEN ... Yes

CREATE ASCII creates a file using LIF ASCII format.

Example Statements

CREATE ASCII "TEXT",100
CREATE ASCII "/Dir1/Dir2/AsciiFile",25
CREATE ASCII Name$&":,700,1",Length

Syntax

Item Description Range
file specifier string expression (see drawing)
number of records numeric expression, rounded to an integer 1 through (231- 1)/256
directory path literal (see MASS STORAGE IS)
file name literal depends on volume's format (see Glossary)
SRM password literal; first 16 non-blank characters are significant > not allowed
volume specifier literal (see MASS STORAGE IS)

Semantics

CREATE ASCII creates a new ASCII file and directory entry on the mass storage media. The name of the newly created ASCII file must be unique within its containing directory. CREATE ASCII does not open the new file; that is performed by the ASSIGN statement. In the event of an error, no directory entry is made and the file is not created.

The physical records of an ASCII file have a fixed length of 256 bytes; logical records have variable lengths, which are automatically determined when the OUTPUT, SAVE, or RE-SAVE statements are used.

Extensible Files

If the file is created on a volume that is not LIF, the file is "extensible". This means that the file system automatically allocates additional space for the file as new data is written to it.

With HFS volumes, the initial size of the file is the size specified in the CREATE ASCII statement, but the file will automatically be extended as many bytes as necessary whenever an OUTPUT operation would otherwise overflow the file.

On SRM volumes, the "number of records" parameter multiplied by the record size (256 for ASCII files) determines the "extent size" of the file (that is, the amount of space automatically appended to the file whenever it is extended).

"Preallocating" the file on non-LIF volumes (initially creating a file of sufficient size) will improve the data transfer rate with extensible files, because the file system will not have to extend the file during data transfer operations.

LIF Protect Codes

On a LIF disk, a protect code is not allowed on an ASCII file. Including a protect code in the CREATE ASCII statement will give an error.

HFS Permissions

In order to create a file on an HFS volume, you need to have W (write) and X (search) permissions on the immediately superior directory, as well as X (search) permissions on all other superior directories.

On HFS volumes, access permission bits are set to RW-RW-RW- when an ASCII file is created. (You can modify them with PERMIT, if desired.) In HP BASIC/UX , permissions may be altered by the users umask. See the HP-UX Reference, umask(1) entry, for more information.

DFS and HFS File Headers

On a DFS or HFS volume, the first 512 bytes of an ASCII file are used by the HP BASIC file system to describe the file's type (this is the only way for HP BASIC to create a "typed" file on an HFS volume, since HFS files are otherwise "typeless"). This file header is handled automatically by HP BASIC , but it should be skipped when reading and writing the file with other HP-UX languages. See the "Porting and Sharing Files" chapter of HP BASIC Porting and Globalization for details.

SRM Access Capabilities (not supported in HP BASIC/UX 700)

In order to create an ASCII file in an SRM directory, you need to have R (read) and W (write) capabilities on the immediately superior directory, as well as R capability on all other superior directories.

When an ASCII file is created on an SRM volume, all access capabilities are public. Including a password in the file specifier does not protect the file. You must use PROTECT to assign passwords. You will not receive an error message for including a password, but SRM passwords in the CREATE ASCII statement are ignored.

CREATE BDAT

Supported On UX WS DOS IN
Option Required None
Keyboard Executable Yes
Programmable Yes
In an IF ... THEN ... Yes

CREATE BDAT creates a file using LIF BDAT (Binary DATa) format.

Example Statements

CREATE BDAT "File",Records,Rec_size
CREATE BDAT "George",48
CREATE BDAT "Protected<PC>",Length,128
CREATE BDAT Name$&Volume$,Bytes,1
CREATE BDAT "/Dir1/Dir2/BDATfile",25,128
CREATE BDAT "/Dir/File:REMOTE",10

Item Description Range
file specifier string expression (see drawing)
number of records numeric expression, rounded to an integer 1 through (231 - 769)/(record size)
record size numeric expression, rounded to next even integer (except 1), which specifies bytes/record; Default = 256 1 through 65 534
directory path literal (see MASS STORAGE IS)
file name literal depends on volume's format (see Glossary)
LIF protect code literal; first two non-blank characters are significant > not allowed
SRM password literal; first 16 non-blank characters are significant > not allowed
volume specifier string expression (see MASS STORAGE IS)

Semantics

CREATE BDAT creates a new BDAT file and directory entry on the mass storage media. The name of the newly created BDAT file must be unique within its containing directory. CREATE BDAT does not open the file; that is performed by ASSIGN. In the event of an error, no directory entry is made and the file is not created. A sector at the beginning of the file is reserved for system use. This sector cannot be directly accessed by HP BASIC programs. This sector is not present on SRM.

Extensible Files

If the file is not created on a LIF volume, it is "extensible". This means that the file system automatically allocates additional space for the file as new data is written to it. With HFS volumes, the initial size of the file is the size specified in the CREATE BDAT statement, but the file will automatically be extended as many bytes as necessary whenever an OUTPUT operation would otherwise overflow the file. On SRM volumes, the "number of records" parameter multiplied by the record size determines the "extent size" of the file (that is, the amount of space automatically appended to the file whenever it is extended). "Preallocating" the file on an SRM volume (initially creating a file of sufficient size) will improve the data transfer rate with extensible files, because the file system will not have to extend the file during data transfer operations.

LIF Protect Codes

On LIF volumes, an optional protect code may be specified; the first two characters become the protect code of the file. (You can modify the protect code with PROTECT, if desired.)

HFS Permissions

In order to create a file on a DFS or HFS volume, you need to have W (write) and X (search) permission of the immediately superior directory, as well as X (search) permission on all other superior directories. When a file is created on an HFS volume, access permission bits are set to RW-RW-RW-. You can modify the permissions with PERMIT. In &nameux, permissions may be altered by the users umask. See the HP-UX Reference, umask(1) entry, for more information. On HFS volumes, the first 512 bytes of a BDAT file are used by the HP BASIC file system to describe the file's type (this is the only way for HP BASIC to create a "typed" file on an HFS volume, since HFS files are otherwise "typeless"). This file header is handled automatically by HP BASIC , but it should be skipped when reading and writing the file with other HP-UX languages. See the "Porting and Sharing Files" chapter of HP BASIC Porting and Globalization for details.

SRM Access Capabilities (not supported in HP BASIC/UX 700)

In order to create a file in an SRM directory, you need to have R (read) and W (write) capabilities on the immediately superior directory, as well as R capability on all other superior directories. When a file is created on an SRM volume, all access capabilities are public. Including an SRM password in the file specifier does not protect the file. You must use PROTECT to assign a password. You will not receive an error message for including a password, but a password in the CREATE BDAT statement is ignored.

CREATE DIR

Supported On UX WS DOS IN*
Option Required SRM & DCOMM, or HFS
Keyboard Executable Yes
Programmable Yes
In an IF ... THEN ... Yes

CREATE DIR creates a directory in either the current working directory or in the specified directory of an SRM or HFS volume.

Example Statements

CREATE DIR "WORK_DIR"
CREATE DIR "/Level1/Level2/New_dir"
CREATE DIR "Level1/Level2/New_dir:REMOTE 21,3"
CREATE DIR "Level1<SRM_RW_pass>/New_dir"
CREATE DIR "Dir3/Dir4:,700"
CREATE DIR "\DATA:DOS,C"

Item Description Range
directory specifier string expression (see drawing)
directory path literal (see drawing)
directory name literal depends on volume's format (14 characters for HFS; 255 characters for long file name systems; 16 characters for SRM; 8 = 3 characters for DFS; see Glossary for details)
SRM password literal; first 16 non-blank characters are significant > not allowed
volume specifier literal (see MASS STORAGE IS)

Semantics

CREATE DIR creates a directory and a corresponding directory entry in the current working directory or specified directory. The DIR file, or directory, keeps information about files and directories immediately subordinate to itself. The name of the newly created directory must be unique within its parent directory. If no directory path is included in the specifier for the new directory, the new directory is created within the current working directory (the directory specified in the latest MASS STORAGE IS statement).

HFS Permissions

In order to create a directory on an HFS volume, you need to have W (write) and X (search) permission of the immediately superior directory, as well as X (search) permission on all other superior directories. When a directory is created on an HFS volume, access permission bits are set to RWXRWXRWX. You can modify these permissions with PERMIT In HP BASIC/UX , permissions may be altered by the users umask. See the HP-UX Reference, umask(1) entry, for more information. As each directory or data file is created within an HFS directory, a 32-byte record identifying the addition is added to the DIR file. The length of this entry is variable for HFS long file name file systems.

SRM Access Capabilities (not supported in HP BASIC/UX 700)

In order to create a directory in an SRM directory, you need to have R (read) and W (write) capabilities on the immediately superior directory, as well as R (read) capabilities on all other superior directories. When a directory is created on an SRM volume, all access capabilities are public. Including an SRM password in the directory specifier does not protect the file. You must use PROTECT to assign a password. You will not receive an error message for including a password, but a password in the CREATE DIR statement is ignored. As each directory or data file is created within an SRM directory, a 24-byte record identifying the addition is added to the DIR file.

DFS Access Capabilities

In order to create a directory on a DFS volume, you need to have W (write) and X (search) permission of the immediately superior directory, as well as X (search) permission on all other superior directories. When a directory is created on a DFS volume, access permission bits are set to RWXRWXRWX.

CREATE WINDOW

Supported On UX WS*DOS*
Option Required RMBUX
Keyboard Executable Yes
Programmable Yes
In an IF ... THEN ... Yes

CREATE WINDOW creates a window for alpha and graphics displays. An error is displayed on invalid parameters, or if the window already exists.

Example Statements

CREATE WINDOW 602,20,50,80*CHRX,24*CHRY,Scrollsize
CREATE WINDOW Plot,Xval,Yval,400,400
CREATE WINDOW 609,100,100,Xsize,Ysize,Scrollbuf; LABEL "Fred"
CREATE WINDOW Graph,400,300,100,100;RETAIN,LABEL "Test Results"

Syntax

Item Description Range
window number numeric expression, rounded to integer 601 through 699
xpos numeric expression, rounded to integer in pixel units integer
ypos numeric expression, rounded to integer in pixel units integer
width numeric expression, rounded to integer in pixel units integer
height numeric expression, rounded to integer in pixel units integer
scroll size numeric expression, rounded to integer specifies scroll buffer size DEFAULT = 0 (units=lines) range of integer, >=0 limited by available memory
name string expression -

Semantics

This statement is only valid when running under X Windows. When not in X Windows, this statement will cause an error.It creates the window specified by the window number with the given attributes.

The xpos and ypos parameters specify the location of the upper-left corner in pixel coordinates. The upper-left corner of the CRT is 0,0. If the xpos and ypos specified are greater than the size of the CRT, then the window is created off the screen and is not be visible until moved onto the screen.

The height parameter specifies the window height in pixels. To create a window with a specified number of alphanumeric rows, multiply the desired number of rows by the function CHRY (the pixel height of a character). The width parameter specifies the width of the window in pixels. Again, to convert alphanumeric columns to pixels simply multiply by the function CHRX.

The scroll size defines how many additional lines (rows) of text can be saved and scrolled within the specified window.

When LABEL <name> is specified, the window name appears in the output of the LIST WINDOW command in the window title bar (if the window manager supports title bars). The resulting title bar contains <name>:xxx where xxx is the window number attribute. The window name is also used as an identifier when the window is iconized. The window name attribute is not used to identify the window within HP BASIC programs. If LABEL <name> is not specified, then only the window number xxx appears in the title bar, and is used as the window name.

The RETAIN attribute specifies whether the raster image of the graphics in a window is saved in memory. The default is not to retain the image, and thus when the window is covered and uncovered, graphics can be lost. HP BASIC ensures that alpha information is always redrawn. The RETAIN attribute can only be specified at window create time. This attribute does have a significant penalty in terms of memory usage. For most monitors with 8 or less planes it requires one byte per pixel to save the image. Monitors with more planes will require more storage. Some new monochrome monitors can store 8 pixels per byte. Note that resizing a RETAINed window causes the window to be cleared, thus all data in the window is lost.

Control statements allow overlapping windows to move to the top of the stack, or be pushed to the bottom.

The CRT may be divided into several rectangular windows, each of which behaves like an independent CRT.

When a window is created, its contents are defined to be blank. If a window exists with the specified window number, an error message is returned.

Windows may be used for alpha, graphics, or both. When working within a window system the alpha and graphics planes are ALWAYS merged. The following statements work with window numbers:


   ASSIGN  @prt to 614  
   DUMP ALPHA 604  
   DUMP DEVICE IS 613       (only for dumping ALPHA)
   DUMP GRAPHICS 605
   OUTPUT 603 ...
   PLOTTER IS  607,"WINDOW"
   PRINTER IS  611
   PRINTALL IS 612

DESTROY WINDOW, MOVE WINDOW, and CLEAR WINDOW statements affect the definitions of the windows.

CRT

Supported On UX WS DOS IN
Option Required None
Keyboard Executable Yes
Programmable Yes
In an IF ... THEN ... Yes

CRT returns 1, the device selector of the CRT.

Example Statements

PRINTER IS CRT
ENTER CRT;Array$(*)

Syntax

CSIZE

Supported On UX WS DOS
Option Required GRAPH
Keyboard Executable Yes
Programmable Yes
In an IF ... THEN ... Yes

CSIZE sets the height and aspect ratio (width:height) of the character cell used by LABEL and SYMBOL.

Example Statements

CSIZE 10
CSIZE 5,0.6
CSIZE Height,Width/Height

Syntax

Item Description Range
height numeric expression; Default = 5 --
width/height ratio numeric expression; Default = 0.6 --

Semantics

At power-on, RESET, and GINIT, the height is 5 graphic-display-units (GDUs), and the aspect ratio is 0.6 (width = 3 GDUs). A negative number for either parameter inverts the character along the associated dimension. The drawing below shows the relation between the character cell and a character.

CSUB

This keyword stands for "Compiled SUBprogram". CSUB statements are subprograms compiled in HP BASIC or another system language, and linked to BASIC by using a special CSUB preparation utility. They are loaded using the LOADSUB statement and can be deleted using the DELSUB statement. When viewed in BASIC's edit mode, these subprograms look like SUB statements, except for the keyword CSUB (instead of SUB). They are invoked with CALL, just like normal SUB subprograms.

Because of their special nature, certain rules must be followed when editing a program containing CSUB statements. These lines will not be recognized if entered in BASIC (they must be created using a system compiler or with the COMPILER binary). Therefore, any operation which requires the line to be checked for proper syntax will fail. This includes such operations as GET, MOVELINES, or re-storing the line by pressing the [Return] or [ENTER] keys. Operations which do not check syntax are allowed. This includes things like scrolling and renumbering.

Sometimes a CSUB will appear as multiple CSUB statements because of multiple entry points. In these cases, the group of statements cannot be broken; you cannot insert a comment line between the statements, delete a single statement in the group, or interfere with the order in any way. The only statements which can be entered directly after a CSUB are SUB and DEF FN. As always, these must be entered at the end of the program.

CSUM

See MAT.

CVT$

Supported On UX WS
Option Required LANGUAGE
Keyboard Executable Yes
Programmable Yes
In an IF ... THEN ... Yes

CVT$ converts one string expression to another according to conversions defined by the LANGUAGE binary. It is useful for localized versions of HP BASIC that support certain languages, such as Japanese.

Example Statements

A$=CVT$(B$,"KATAKANA TO HIRAGANA")
A$=CVT$(B$,"ZENKAKU TO HANKAKU")

Syntax

Item Description Range
input string string expression any valid expression
conversion specifier string expression depends on LANGUAGE

Semantics

The CVT$ function is used in certain localized versions of HP BASIC , such as Japanese localized HP BASIC . These local languages often use more than one alphabet. CVT$ converts the input string character-by-character from one alphabet to another, according to the conversion specifier. The choices and default values available for conversion specifers depend on the particular LANGUAGE binary you are using. For a general discussion of globalization and localization, refer to HP BASIC Porting and Globalization. For LANGUAGE specific details, refer to Using LanguageX with HP BASIC, where LanguageX is your local language.

CYCLE

See OFF CYCLE and ON CYCLE.