A-Shell Consolidated Reference

Rewritten April 2024

xcall MIAMEX, MX_GETQUEUE, blkno, qblock

MX_GETQUEUE (MIAMEX 30) reads queue blocks from the system queue file (qflock.sys).

Parameters

blkno  (Unsigned Int)  [in]

Block (record) number to read.

qblock  (Struture)  [out]

Structure to receive the block. The two structure definitionsm, ST_QHEADER for the control record and ST_QBLOCK for the other blocks, are defined in the file ashinc:qflock.sdf as follows:

defstruct ST_QHEADER              ! Queue header block

  map2 QFREE,b,2            ! Free queue pointer

  map2 QUSED,b,2            ! Used queue pointer

  map2 Q'HIGHWATER,b,2      ! Highest used record #

  map2 LOG'COUNT'NOMORE,b,2 ! Logical users (instances) count [13]

  map2 Q'VERSION,s,4        ! version

  map2 Q'TOTOPS,i,4         ! total q adds & deletes

  map2 Q'TOTREADS,i,4       ! total q adds & deletes

  map2 Q'TOTWRITES,i,4      ! total q adds & deletes

  map2 DUMMY1,x,16          ! Dummy filler was 24 [13] was 28 [34] was 24

endstruct

 

defstruct ST_QBLOCK         ! qflock record

  map2 QNEXT,b,2          ! Pointer to next queue block

  map2 QTYPE,b,2          ! Queue block id type

  map2 QOWNER,b,2         ! Owner of queue block

  map2 QJUNK,b,2          ! (get back to 4x alignment)

  map2 QDATA              ! 32 bytes of data  (was 34)

  map2 QD'FLOCK,@QDATA    ! Format of FLOCK record

     map3 ACTION,b,2     ! Action

     map3 MODE,b,2       ! Mode

     map3 RECORD,b,4     !  Record number

     map3 CHANNEL,b,4    ! Channel number [12] was 2

  map2 QD'IFLOCK,@QDATA   ! Format of inactive FLOCK record

  map2 QD'XLOCK,@QDATA    ! Format of XLOCK record

     map3 LOCK1,i,4      ! Primary lock code (INTEGER!)

     map3 LOCK2,i,4      ! Secondard lock code (INTEGER!)

     map3 LOCK3,b,2      ! New lock class (0=xlock,1=lock)

endstruct

 

The ST_QBLOCK structure supports multiple layouts via overlays; the QTYPE field indicates which of the overlays to use, according to the following table:

Comments

MX_GETQUEUE is used primarily to track various kinds of inter-process locks or semaphores, in particular by the subroutines XLOCK and FLOCK.

The number of queue blocks is set by the QUEUE statement in miame.ini.

Logically, the queue blocks are organized into two linked lists, one for the blocks that are in use (starting with the block number specified in the ST_QHEADER.QUSED field), and the other (ST_QHEADER.QFREE) for the available blocks. In either case, you can follow the linked list via the ST_QBLOCK.QNEXT field.

Note that in a multi-user environment, the two linked lists may be actively updated. In order to traverse one of the lists safely, you should first lock the control via MX_QLOCK and unlock it when done using MX_QUNLOK.

See Also