Updated June 2016; see History

xcall LOG, logstr {,qflag, status}

xcall LOG, dev, p, pn

LOG.SBR allows you to log to a new disk and PPN, using an ersatz or traditional specification, with an option to silence the normal output (start message) that you would otherwise see with an AMOS LOG command. It may also be used to return your current device, project, and programmer number.

Parameters

logstr  (String)  [in]

A string specifying the desired device and/or PPN to log to.  Any of the formats accepted by LOG.LIT are accepted here.  See examples below.

qflag  (String)  [in]

If specified and non-null, silences the normal confirmation message that you would see when logging into a new location. By convention, qflag is set to "Q" to indicate this "quiet" mode.

status  (F6)  [in/out]

If specified and set to a non-zero value on input, the routine will validate the target device and ppn, and return 0 for success, or a system error number for failure.  Note that you must initialize the variable to a non-zero value for this validation to occur.  Otherwise, it will still return -1 if the target device is invalid, but it will not validate the PPN, and thus it would appear to allow you to log into a non-existent PPN. See History.

dev  (String)  [out]

Returns current logged-in device, in upper case, with no trailing spaces or punctuation, e.g. "DSK0".

p  (String)  [out]

Returns decimal string representation of current "project"(1st part of PPN), e.g. "1" or "200"

pn  (String)  [out]

Returns decimal string representation of current "programmer number" (2nd part of PPN), e.g. "4" or "921"

Examples

xcall LOG,"SYS:"               (log to SYS:)

xcall LOG,"LOG DSK0:[1,4]      ('LOG' is optional)

xcall LOG,"SYS:","Q"           (silence output)

xcall LOG,DEV$,P$,PN$          (return current login)

Comments

The routine determines which operation to perform—log to a new location or return the current location—based on the number and type of parameters passed. If 3 arguments are passed and the 3rd argument is not a floating point variable, it returns the current location; in all other cases it treats the operation as a request to log to a new location.

Note that by returning the PPN as a pair of decimal-formatted strings, this routine avoids the issues related to octal vs. decimal representation and single-byte overflow that may affect routines that manipulate the PPN as a pair of binary values.

History

2016 June, A-Shell 6.3.1515:  Status now returns numeric error codes on failure rather than just -1.

2009 September, A-Shell 5.1.1159:  The routine was modified to support returning data into dynamic variables, such that they expand as needed. Previously, the output data was being truncated to the current size of the variable, or 0 for uninitialized.