461845 001_Extended_i RMX_II.3_Volume_2_Users_Guides_1988 001 Extended I RMX II.3 Volume 2 Users Guides 1988

461845-001_Extended_iRMX_II.3_Volume_2_Users_Guides_1988 461845-001_Extended_iRMX_II.3_Volume_2_Users_Guides_1988

User Manual: 461845-001_Extended_iRMX_II.3_Volume_2_Users_Guides_1988

Open the PDF directly: View PDF .
Page Count: 832

Download
Open PDF In Browser	View PDF

intel'
E X T E N D EiD
RMX@II.3

OPERATING
SYSTEM
DOCUMENTATION
VOLUME
2
U S E R 'G
SU I D E S
O.derNumber:461845-001

IntelCorporation
3065BowersAvenue
SantaClara,Californla
95051

o 1988,IntelCorporation,
Copyright
Ail RightsReserved

In locationBoutside the Uúited Stata6, obtain ailditionsl copi€s of Iniel docuúentation by
contectingyour jocal Iniel salesofice. For yoù conveni€.ce,int€rnaiionsl salesofiice rddr€ss€s
arc locateddircctlybeforetlìe readÈr.€ply.ardiirtrùÙàckollhe nuîual,
The infornation

in Lhis do.uhent is subj€ct to change wiihoui noiice.

Inrel Corporation makes no warranty ofany kind with regard io rhi6 mat€rial, inclùding, but not
Ìimit€d to, the impiied ù arrantie6 of merchantsbility and Iithess fo. a parlicùlù pufpose. Iniel
Co.poration assumesno responsibility lo. any errors ihai may appear in ihi6 documeùt. Intel
Corporation makes no connitmentto update or to keep currentthe informùtioúcontained iù this

Iùtel Corporation assune6 no respohsibility lor the se of any circuilry other rhan circuit.y
ehbodied in an Intel prodùct. Noothercircuitpatentlicensesare impliedInt€l $ftware p.oducts a.e copyrighted by and shall renain the property of Ìntel Corpofaiion.
Use, duplicaiio! or di6closureis subject to restrictions stated in Intel's soltwaré li.ebse, or as
detinedinASPRT 104.9(a)(9).
No paú olthis documentmèy be copiedor rèproducedin any form or by any meanswithout prior
wÌitt€n cons€ntoIInt€l Corporation.
The fouowins are tradeúÉrks of Intel Corporation and ik amliaies and nay be Èed only 10
id€ntily Intel producls:

Above
BTTBUS
COMMputer
CREDIT
Daia PipeÌine

iLBX
im
ilfDDX
iMMX
Ìnsite

i
i
I2ICE
ICE
iCEL
iCS
iDBP
iDIS

irtèIBOS
lntelevision
nrieligEtrLldcltifier
MCS
inteligentProgrùmming
Intellec
MICROMAINFRAME
lrtellink
MULTIBUS
iOSP
MULTICHANNEL
iPDS
MULT!MODULE
iPSB

iPSC
iRMX
iSBC

ONCE

isBx

PROMPT

iSDM
issB
iSXM

QUEST
Qùex
RM}V80
RUPI
SLD
UPI
VLSiCEL

XENIX, MS-DOS,
Multiplan,and Microsoftare t.ademarksofMicrosoltCo.poraiion.SNIX is a
trademarkof Bell Laboratori€s.
Ethe.netis a trademsrl.
DELE'TESSEGMENT

Figure 5-1, Memory MoYementDiagmm

NucleusUserrsGuide

MEMORYMANAGEMENT

5.6.1BufferPools
Buffer Poolsare holdingareasfor segments
jwhichare usedby taskswhenneeded.
pool
Havinga
of memoryreadilyavailabletqitaskscursdownon systemoverheadbecause
allocatingthe existingbulfers is fasterthancleatingand deletingsegmeots.
Buffer poolsare emptywhencreated. The {rsergivessegmentsro the buffer pool. The
segmentsare createdùsingthe the RQ$CREJTE$SEGMENTsystemcall. The created
segmentsare givento a buffer pool by usingitheRQ$RELEASE$BUFFERsystemcall.
The buffersare then usedby tasksthaî requirememory. Any taskthat reqùiresfrequent
creationand deletionof segmentsmayimproveperformanceby usinga bulfer pool with
pre-allocatedsegnents.
Buffer poolsincur a certair amountof systemoverheadin their creation. The following
formùla definesthe amoufitof resourcesrequircd.
(Max Bufîers * 4) + 108bytes= the amountof memoryusedby anygivenbuffer pool.
lvhen you createa buffer pool you specifuthe followinginformatiol:
r

the maximumnumberof buffersthat canresidein the buffer Doolat anvone time
18192maximùm.l

5.7 SYSTEM
CALLSFORMEMORY
MANAGEMENT
The systemcallsfor úemory managementare

5-4

CREATE$BUFFER$POOL-CreateS
a buffer pool object.

CREATE$SEGMEI',lT--creates
a s€gmentandreturnsa token for it.

DELETE$BUFFER$POOL-DeIeIeSa buffer pool objept.

DELETE$SEGMEM-returns a segmentto the pool from $hich it wasallocated.

GET$SIZE-returnsthe size,in bytes,of a segnent.

RQE$GET$POOL$ATTRIB-IeIuInSthe followingmemorypool atftibutesofîhe
specifiedjob: pool minimum,pool maximum,initial size,numberof allocated
paragraphs,numberof availableparagraphs,andthe arnourÌtof memoryborrowcd.
Bothpoolminimumandpool maximummaybe up to 16Mbltesofmemory.

cEl$POOL$ATTRIB-returùs the followingmemorypool attributesof the calling
task'sjob: pool úinimum, pool maximum,initial size,numberof allocaîed
paragraphs,and numberof availableparagraphs.Borh pool minimumaridpool
maximumare limited to 1M byte of memory. This systemcall is providedfor
compatibility,withthe iRMX I OperatingSysrem.Ilov.€v€r,for newapplicatioosuse
RQE$GET$POOL$ATTRIB.

RELEASE$BUFFER-ReIuIna (segment)buller to a previouù oeated buffer pool.

NucleusUset'sGuide

\--'l

MEMORYMANAGEMENT

REQUEST$BUFFER-Geta buffer (segrient)ftom a buffer pool that hasbeen
sùppliedwith buffersvia the RQ$CREAIE$SEGMENTsystemcall.

For a completelist and explanationof the iRMX II Nucleussystemcalls,seetheExtended
|RMX II NucleusS)aternCallsMercnce Manual.

NucleusUset'sGuide

5-J

5.1 INTRODUCTION
The Nucleusprovidesthe objectsfrom whichthe other subsystems
are constructed.The
Exended iRMX II Nucleususes16-bitvalues,calledtokens,to managethe objectsin the
system.Tokens,asdefinedby the iRMX II OperatingSystem,are logicaladdresses.
They are selectorsthat referencean entry io the globaldescriptortable (cDT). It is the
GDT entrywhichcontainsthe 24-bitphysicaladdressof the memoryusedby the object.

6.2 ACCESSRIGHTS
One of the protectionleaturesof fhe 80286processoris the ac{€ssbyte. This byte
containsthe attributesof an 80286segment,that is, it definesthe waya segmelt canbe
usedby instructionsin other 8028ósegments.Whenan iRMX II obje.t is created,its
correspondingsegrnentis assigÌeda read/write accesstype. Beîoreanyoperationis
performed,the hardrvarechecksthe accesst,:pe, If yoù haveenteredthe wlong access
type,the hardwarecausesan exception.The iRMX -ll OperatingSystemhastaken
advantageof this hardwarefeatureby allowinga taskto changean object'saccesstypefot
segÌflefltobjects,descdptorobjectsor composireobjects.Accessrights for all other object
typesfob, task,mailbox,semaphorgregionandextension)cannotbe changed.
Two systemcallsare providedfor nanipulatingthe accessblte.
RQE$GET$OBJECî$ACCESS
suppliesthe valueof the object'saccessbJte. The
RQE$CIJANGE$OBJECI$ACCESS
systemcall allowsyou to changean object'saccess
dghts. It usesîhe accessbte format providedby the 80286processorfor both codeand
datasegmentdescriptors.For a list of the possibleac4essblte valùes,seetheExtend,ed
iRlttx II NucleusS,rstetu
CallsReferekce
Mahual.

NOTT
Do not try to changebits in a token. This maycausea hardwaretrap.

Nùcleùs Uset's Gnide

6-1

OBJECT MANA.GEMENT

6.3 OBJECTADDRESS
The RQE$GET$ADDRESSsystemcall mnvertsao object'slogicaladdrcssinto its 24-bit
physicaladdress.The physicaladdressmaybe nscessary
whenusingdevicedriveN or
whencreaîingaliasesaspart of descriptormanagement(seeChapter7).

6.4 TNQUIRING
ABOUTOBJECTTYPES
The GET$TYPEsystemcall enablesa taskto presenta token to the Nucleusand get an
object'stype codein return. (T)?e codesfor Nucleusobjectsare listed in AppendixB.)
This is useful,for example,whena taskis expectingto receiveobjectsof severaldifferent
rypes. With the obje.t's t'?e code,the taskcanusethe apprcpriatesystemcallsfor the
object.

6.5 USINGOBJECTDIRECTORIES
Eachjob hasits own objectdirectory. An ertry in an objectdirectoryconsistsof a token
for an objectandthe objectname. The namecontainsfrom one to twelvecharacters,
wherea characteris a one-b1tevalue(from 0 to oFFH). Sucha featureis often needed
becaùsesometasksmight only knowsomeobjectsby their associatednames.
By usingthe LOOKUP$OBIECT systemcall,a taskcanpresenîthe nameof an objectto
the Nucleùs.The Nucleusconsultsthe objectdirectorycorrespondingto the specifiedjob
and,if the objecthasbeencatalogedthere,returnsthe token,

NOTE
In objectdLectories,upper andlov.ercasealphabeticcharactersare
treatedasbeingdifferent. The Nucleusseesthe nameasjùst a stritg of
b]'tes. It doesnot interpret thesebytesasASCII characters.
If the objecthasnot yet beencataloged,and the taskis not willing to wait, the task
remainsreadyandreceivesan E$TIME exceptionalcondition(unlessthe objectdiectory
is full, in whichcasethe taskreceivesan E$LIMIT conditioncode). However.if the task
is willingto wait,it is put to sleep;thentwopossibilities
exisr:
. If the designatedwaitingperiod elapsesbeforethe taskreaeivesits requestedtoken,
the taskis madereadyandreceivesan E$TIME exceptionalcondition(seeAppendix
D).
.

6-2

If the taskreceivesits reqùestedtokenwithh the designatedwaitingperiod,it is made
readywith Doexceptionalcondition. This ceseis possiblebecauseariothertaskcan
catalogthe appropriateentry in the specifiedobjectdirectorywhile the requesting
taskis waitine.

NucleusUsefs cuide

OBJECTMANAGEMENT

í--\

Whena taskwantsto sharean objectwith the other tasksin a job (noî necessarilyits own
job), it canusethe CATALOG$OBJECTsystemcall to pùt the objectin that job,sobject
directory. Trpicaly, this is doneby the creatorof the obj€ct. Likewise,entriescanbe
removedfrom a direrctoryby the UNCATAIOG$OBJECT systemcall.
Whenusingan objectdirectory you mustgivethe rokenof thejob whosedhectoryis to
be used.The rootjob'sobjectdirectorycalledthe root objectdiectory,is specialin thar
its token is easilyaccessible.Any taskcancall the GETSTASK$TOKENSsystemcall to
obtainthe tokenof theroot iob.

6.6 SYSTEMCALLSFOROBJECTS
The following systemcalls manipulate objects:
.

cATALocgOBJECT-places

GET$TYPE-accepts a token for an object and returns its t)?e code.

LOOKUP$OBJECT-acaepts a catalogedname of an object and rcturns a token for it.

RQE$CHANGE$OBJECI$ACCESS--changeS the accessbyte of an object.

RQE$GET$ADDRESS-ietùrnS the physical addressof an object.

RQE$GET$OBJECI$ACCESS-reIuInS
îhe valueof an objert'saccessbfe.

UNCATALOG$OBJECT-remoVeS aî object ftom an objept directory.

an object in an object dire4tory,

For a complete list and explanation of the iRMX Il Nucleus system calls, see the Extended
|RIUIXII Nucleu.sSysteh CaIk ReferenceManual.

Nùcleùs Usefs Guide

7.1 INTRODUCTION
Descriptorsare usedto addressan areaof memory. Everysegmentmusthaveat least
one descriptoror it is not addressable.Eachdescriptoris an entry in the GDT and
containsîhe physicaladdress,the accessrights,andthe segmentfmits.
The Nucleusassignseachobjecta descriptorwhenit is created.This g/peof descriptor
maybe thoughtof asan implicit descriptor.Implicit descriptorsare managedby the
OperatingSystem.Applicatiol programmersdo not needanyadditionalinformation
aboutdescriptorsand maywant to skipthe rest of this section.

7.2 EXPLICITDESCRIPTORS
The systemprogrammershouldknowthat thereis a secondtype of descriptorwhichcan
be thoughtof asan explicitdescripto.. Explicit descriptorsaîe usedprimarily for the
followingpurposes:
.

To gain addressabittyto areasof memorythat are not definedwhenthe systemis
codigured andthùs,haveno logicaladdress,

To createaliasg!to existìng
segments(AJiases
areoneof severaldescriptors
tlat
maybe necessary
to definea diffeîent segmentq?e or a different accessright for the
samesegment.)

To adddevicedriversto the system.(SeetheExtehdedLRMXII Batíc I/O Sfstem
User'sGuide.)

You canmanipulatedescriptorslike segments.You caocreate,chalge and deletethem.
In fact,to the operatingsystemtheylook just like segments.If you call GEISTYPE on a
descriptor,the type codereturnedis for a segment.

NucleusUsels cuide

7-l

DESCRIPTORMANAGEMENT

Greatcareshouldbe takenwhericleatiflg a descriptor,By calling
RQE$CREATE$DESCRIPToRit is possibleto createa descriptorfor anyphysical
address.Aí elror in calculatingthe physicaladdressmay overwritevaluablesystem
informationsuchasthe GDT. Whenyou createa descriptora hardwareslot is
establishedin the GDT with the requiredphysicaladdress.The Nucleusmarksthe object
asa d€scriptor. In this way,the Nucleus'knoì,vs"that whenthe descriptoris deleted,using
RQE$DELETE$DESCRIPTOR,
only the cDT slot is to be recycled,not the memory
addressedby the descriptor.
The iRMX tr OperatingSystemalsoprovidesthe RQE$CHANGE$DESCRIPTOR
systemcallwhichcanbe usedto changethe physicaladdressof a descriptorand/or the
lengthof the segmentaddressed.This systemcall is particìiarly usefulin applìcationsthat
includeI/O drivers.

7.2.1Descriptors
withAliases
As sîaîedabovg you canusedescriptorswith aliasesandwith areasof memorythat were
not definedat configurationtime. Aliasesallowyou to haveseveraldescriptorsfor the
samesegment.Theyprovidesegmentswith alternatenamesin muchthe same\ì/ayas
peopleusenicknames.Deletingan aliasdescripîordoesnot deletethe segmenîto which
it refers.

7.2.2Descriptors
lor Undefined
Memory
Descriptorscanalsobe usedto gainaddressabilityto areasof memorythat wete not
definedwhenthe systemwasconfiguredandthus,haveno logicaladdress.Thesememory
areasare not allocatedftom thejob's mernorypool. Whentheyare creatodthcy do not
reducethe sizeof the memorypool. Therefore,whentheyare deleted,theydo not reîurn
memoryto the memorypool.

7.3 CAUTIONARY
NOTESON USINGDESCRIPTORS
Descriptorsa.e a very powerfulfeatu.eof the operatingsystem.If theyare úisused,they
cancanaffect the htegdty of the entirc operatingsystem.If you wish to preservethe
int€grity of your applicationsystem,confineth€ useof descriptorsto experienced
programmerswho havea firm understandingof iRMX tr addressing.A lessL'nowledgeable programmer can, by abusing descriptoG, coffupt the interasrion bot$/ccn

tasksin an applicationsystem.

7.4 SYSTEMCALLSFORDESCRIPTOR
MANAGEMENT
The followingsystemcallsmanipulatedesrTiptors.

NucleusUset's Guide

DESCRIPTORMANAGEMENT

.
.
r

RQB$CREATE$DESCRIPTOR-reIùrDS
a segmenttoken for an entry in the cDT.
ROE$CIIANGFJDESCRIPTOR-ohangeS
the physicaladdresscontainedin the
GDT ard/or the sizeof the segmentdescdbed.
RQE$DELETE$DESCRIPTOR-IeIurISa slot from the cDT to the operating
systemfor reuse.

For a completelist and explanationof the iRMX II Nucleussystemca)ls,seetheExtended
|RMX II NucteusSystemCalk Relerence
Manual.

NucleusUset'sGuide

8.1 INTRODUCTION
lvhen a taskilrvokesan iRMX II systemcalt sometimesthe resultsare riot what the task
is trying to achieve.For examplga segmentaccessmayoverflowits boundariesor a task
mayrequestmemorythat is not available.In suchcases,the operatingsystemmust
inform the taskthat an error occurred. Whenevera taskmakesa systemcall or the 8028ó
processortrapsan illegal condition,the systemusesa conditioncodeto commudcatethe
sùccessor failure of the call.

8.2 CONDITION
CODEVALUESAND MNEMONICS
Conditioncodesare numericvaluesthat representuniqueconditions.Eachcondition
codeal$ohasa mnemonic(suchasE$OK), to indicatethe code'smeaning.AppendixD
lists the conditioncodesv/ith their numericvaluesandmnemonics.
Whenwriting applicationtasks,you canrefer to the conditioncodesby their mnemonics
aslong asyou declareeachmnemonicarìdits numericcodeto be liaerallyequal. Intel
suppliesthe /RMX286/INC/ERROR.LIT file whichcontainsliteral declarationsof all
the iRMX II conditionmde mnemomcs.

8.3 TYPESOFEXCEPTIONAL
CONDITIONS
Conditionsthat representfailùre (or not completesuccess)are calledexc€ptional
conditions.Theseconditionshavetwo classifications:programmererrorsand
environmentalconditions.A plggqlqlqgrcllq! is a conditionthat the callfuigtaskcan
preveùt. lrr contrast,an envtonmentalconditionadsesoutsidethe control of the calling
task. Se€AppendixD for a completclist ol both programmererrofs andenvironmental
cofIditions.

8.4 CONDITION
CODERANGES
The valuesof conditioncodesfall into rangesbasedon the iRMX II layerwhichfirst
detectsthe condition. Table8-1lists the layersandtheil respectivetanges,with numeric
valuesexpressed
in hexadecimalnotation.

NucleusUset's Gnid€

8.1

EXCEPTIONAL CONDITION MANAGEMENT

Table8-1, ConditionCodeRanses
Environm€ntal
Nucl€us 0HtooFH
l/O Sysi6ms
ApplicationLoad€r
lJniversal
Dev€lopm€nt
lnt€rfac€

Programming
Erors

8000Hto 800FH
20Hro sFH
6OHto 7FH
80Hto AFH
CoHto DFH

ao20Hro 805FH
8060Hto 807FH
€O€OH
to SOAFH
80@H to 80DFH

EOHto 3FFFH
400oHto TFFFH

80E0Hto BFFFH
C000Hto FFFFH

8,5 EXCEPTION
HANDLERS
The iRMX II Nucleussupportsexceptionhandlerswhichdealwith the erors that tasks
encounterin makingsystemcalls. How an exceptionhandlerdealswith an et(ceptional
conditionis a matter of programmerdiscretion.In general,a handlerpedormsone of îhe
followingactions:
.

Ings the error.

Deletesor suspends
the taskthaterred.

Igrores the error. lf this option is taken,the systemcontinuesasif flo effor had
occurred. Continuingundersuchciacumstances
is generallyunwise,however,

An exceptionhandleris written asa procedurewith four parameterspassedin the
followingorder:
.

The conditioncodeIWORDì.

A code(BYTE) indicatingwhíchparameter,if any,wasfaulty in the call (1 for first, 2
for second,etc,,0 if none).

-Areserved(WORD) paîameter.

A (WORD) parametercontainingthe NumericProcessorExtension(NPX) status
word. This paramctcris valid only if the conditioncodeis E$NDP$ERROR,

8.6 ASSIGNING
AN EXCEPTION
HANDLER
A taskmayusethe SET$EXCEPTION$iIAN.DLERsystemcall to declareits own
exception
handler.Otherwise,
thetaskinheritsthe exception
handle.of its job. A job can
receiveits own exceptionhandlerat the time of its cleation_lf it doesn,t,the job inherits
the systemexceptionhandler. Thus,the Nucleuscanalwaysfind an exceptionhandlerfor
therunningîask.

8-2

NucleusUsefs Guide

EXCEPIIONAL CONDITIONMANAGEMEM

A systemexceptionhandleris providedasparr of rhe iRMX II OperatingSystem.When
you configurethe system,you mayspecilythe SystemDebugger,SDB,asthe system
exceptionhandler(this is conveniontfor debuÉging).In this case,LhciRMX II Operating
Systemlets the monitor andîhe SDBdebuggertakecontrol of all the 80286hardware
exceptions(exceptthosethat handlethe Nùúeric Proc€ssorExtension).This meansthat
the monitor, in conjunctionwith the SDB debugger.will alwayshandlehardware
exceptions(causinga breakto the monitor,andsendinga messageto the console),even
for iRMX II task$that specirytheir own exceptionhandler. A user-wdttenexception
handlermaystill be invokedto handleenors detectedin the ìRMX Il systemcalls.
ff youwant to write your own exceptionhandlers,compilethem usingthepL/M-286
I-ARGE control,specifyingthe PUBLIC attribute, It is alsopossibleto compileexception
handleîsusingthe COMPACT control,aslong asthe followingconditionsare met:
. One extradummyword parameteris addedto the callingsequence(at the endof the
parameterlist).
. The exceptionhandlermustbe in the samecodesegrientasthe taskit serves.
.

The exceptionhaDdlerdoesnot handlehardwatetraps.

8.7 INVOKING
AN EXCEPTION
HANDLER
An exceptionhandlerùormallyr€ceivescontrolwhenan excepîionalcooditionoccurs.
However,Ìr'hena task encountersan exceptionalcondition,it neednot alwayshave
conhol passedto its exceptionhandler. The factor that determineswhethercontrol
passesto the exceptionhandleris the tasks exceptionmode. This attdbutehasfour
possiblevalues,eachof whichspeciiiesthe circumstarìces
underwhichthe exceptiot
haldler is to get control in the eventof afl exceptionalcondition. Thesecircumstances
are
o Programmererrorsonly
.

Environmentalconditionsonly

All exceptionalconditions

No excepîionalconditions

Whenthe Nucleusdetectsthat a taskhascausedan exceptionalconditionin makinga
systemcall,it compaîesthe type of the conditionwith the callingtasks exceptionmode.
If a transf€rof contlol is indicated,the Nucleuspassescontaolto the exceptionhandleron
behall of the task. The exceptionhandlerthen dealswith the problem,after whichcontrol
returnsto the task,unlessthe exceptionhandlerdeletedthe task. Whenthe exception
handlerreturns,the taskcanalsodetectthat afl elror occured. becausethe wstem call's
except$ptr
parameter
por'ntsto a wordcontaining
theconditioncode.Whileihe
exceptiol handleris executing,the errant taskis still regardedby the Nucleusto be the
runningtask. Therefore,the exceptionhandlertaskusesthe stackand envionment of
the eúaflt task.

NucleusUset'sGuide

8-3

EXCEPTIONAL CONDITION MANAGEMENT

Whena taskis created,its exceptionmodeis setto its job's defaultexc€ptionmode. The
taskcanchaogeits exceptionhandlerand exceptioomodeattributesby usingthe
SET$EXCEPTION$IIANDLERsystemcall.

8,8 HANDLINGEXCEPTIONS
IN.LINE
If a task'sexceptionmodeattribùte doesnot direatthe Nucleusto transfercontrol to the
task'sexceptionhandler,the responsibilityfor dealingwith an error falls on the task.
Eachsystemcall hasasits last parametera POINTER to a WORD. After a systemcall"
the Nucleusreturnsthe resultingconditioncodeto this WORD. By checkingthis WORD
atter eachsystemcall,a taskcaodeterminewhetheror not the call wassucce$sful.(See
AppendixD for conditioncodes.)If the call wasnot successful,
the taskcanlearnwhich
exc€ptionalconditionit caused.This informationcansomefimesenablethe taskto
recover. In other cases,more informationis needed.
If a systemcall returnsan exceptioncodeto indicatean unsuccessful
call"all other output
parametersof that systemcall are undefined.

NOTE
If an invalid parameter causesan exceptioîal condition it should be
handled by an exception handler. When using Nucleus systemcalls, the
handler receivesthe parameter number of the first invalid parameter.

8.9 HANDLINGEXCEPTIONS
IN 80286PROCESSOR
SYSTEMS
The followingsectioflsare particularlyimportantfor userswho are familiar wiîh rhe
iRMX 86 OperatingSystem.The increasedprotectionîeaturesof the 8028ó
microprocessor
haveresultedin a diîfcrcnt wayof handling€xceptionsandn€wexception
codes.
The operatingsystemsoftware"catches"andreturnsmost of the exceptionalconditions.
However,a few conditionsoccurbecausethe mictoprocessorcatches(or traps) an invalid
condition. The trap causescontrcl to be passedto specialexceptionhandlingcodewhich
the iRMX II OpefatingSystemprovides.This codeexaminesthe exceptionmodeof the
current task andactsin one of the followingways.

8-4

It maycall a system-supplied
exceptionhandler-

It maycall a user-suppliedexceptionhandler.

lt may .etum contol dftecdyto the faulting iRMX II task.

NucleùsUset's Gnide

EXCEPTIONALCONDITIONMANAGEMENT

For 80286processod,
a CPUtrapsetsthe instruction
pointer(IP) fegisterto pointto the
instructionthat causedthe CPU trap. This differencerneansthat without an exception
handler,an 80286-based
applicationcannevergct pastthc instructionthat causedthe
CPU trap.(Usersfamiliarwith 8086,88,186,or 188processors
will rememberthatwith
theseprocessors
a CPUtrapsetstheIP registerto pointto the instructionaftertheone
that causedthe CPU trap, This situationallowssomeapplicationsto ignoreerrorsand
continueprocessing.)
Therelorg for 80286-based
you shouldalwaysdesignatean exceptionhandlerto
systems,
handleexceptioncodesgeneratedby CPU traps(programmingerrors),evenif the
handlerdoesnothingmo.e thanincrementthe IP valuethat is pushedonto the task's
stackwheothe tmp occurs(thaî is, the retunì address).Without a handlerof somekind,
yoùr applicationwill get caughtin an infinite loop in the eventof a CPU trap.
Iî youusethe exception
handlersupplied
with theoperatingsystemto handle
programmer
erors, yourapplication
will run thesame,regardless
of the CPU. However,
if youwriteyourownexception
youshouldincludecodeto handleeitherof the
handlers,
sitùationsmentionedin this section.
Ifyou haveuser-writtenexceptionhandlersthat are beingupgradedfrom the iRMX 86
OperatingSystemto theiRMX II OperatingSystem,
be sureto changethecodein
exceptionhandlersfor the divideby zero trap. In the iRMX 86 OpemtingSystemafter a
divideby zero,the Nucleusrelurnsto the nextinstructionwhereas,in the iRMX II
Ope.atingSystem,
theNucleusrctumsto the sameinstruction.If youdo not ensurethat
the retum addressis the nelú instruction,you couldget caùghtup in an infinite loop. Intel
recommendsthat you upgradeall user-writtenexceptionhandlersto enablethem to
handle the new exception codes.

Table8-2liststheconditions
whichmaycausea trap andtheinstructionto lvhichit
returns.The tablealsocompares
the handlingof aniRMX II exception
with an iRMX 86
(if youareoperatingtheiRMX 86OperatingSystemon an 80286processor).
exception
Someexceptions
suchaspowerfailuredo not returncontrolto the faultingtask. These
exceptionshavebeenmarkedN/A (not applicable).

NucleusUset'sGuide

ù-5

EXCEPTIONAL CONDITION MANAGEMENT

Table8-2. Retun Addressaller an Exception
lmtruclion R€tumedTo

Int€rrupt
De8cription

0
I

2
3
4
5
6
7
I
9
10
tl

Divid€by zero
Singls6t€p
Pow€rfailure(non-maskable)
One byte interupt inrtuciión
Interrupton ovsrflow
Runtimearay bound€Íor
NPXnot preservNPx task sdtch
Doubtefauh
NPXsegmentoverun
lnvalidTaskStat€S€gmerìt
S€gm€ntnot preserìt
Stack€xc€ption
G€nelalProtection
ProcossorExtensionEíor

IRMXll IRMXAOon ao2a6Processor
Sam€
Ned

Sam6
Nex

N€xt
Same
Sam6
Same

Next
Samg
Sam€
Sam6

N/A
Sam€

N/A
N/A

Sam6
N/A

Same

If your systemsupportsan 80287NumericProcessorBxtensiol (NPX, somereferencesto
NDP in the error codesare for cornpatibilityreasons)exceptions7, 9 and 16maybe of
specialinterestto yoù. Interrupt 7 mayoccuron systemsthat supportan NPX and on
thosethat don't. If your systemdoesnot havean NPX andyou receiveinterrùpî 7, treat it
asyou wouldanyother programexception.However,if your systemhasan NPX and
interrupt 7 occurs,do not try to serice it asInterrupt 7 is reservedfor the system.A
conîextswitchof the NPX environmenttakesplaceandthe faultirigtaskcontinues.
ln the eventof interrupts9 or 16,the retum addressis that of the cùrrent instructiofl
However,the exceptionwascausedby the previousNPX instruction. This is true because
the 8ù287NPX, unlike the 8087NP)i, doesnot causean exceDtionassoonasan crror
occurs.An excepîioîr
occursonlywhenthenelt floatingpoiniinstructionin the sametask
is executed.

8.10 SYSTEM
CALLSFOREXCEPTION
HANDLERS
The followingsystemcallsmanipulateexceptionhandlers:
.

SET$EXCEPîON$iIANDLER-seIs the exceptionharidlerandexceptionmode
attributesof the callingtask.

GE]SEXCEP{ION$IIANDLER-retumS to the callingtaskthe cùrrentvaluesof its
exceptionha[dler arldexceptionmodeattributes.

For a compleîelist and explanationof the iRMX II Nùcleussystemcalls,seetheExtended
íRMX1I NucleusSystemCallsRefereceManuùl.

8.6

NucleusUset's Guide

9.1 INTRODUCTION
Interrupts andinterrupt processingare centralto real-timecomputing.Externalevents
occurasynchronouÙwith respectto the ilternal workingsof an iRMX II application
system.An interrupt, signallingthe occurrenceof an efernal event,triggersan implicit
"call"usingan addresssuppliedin a sectionof memoryknownasthe ioterrupt descriptor
table. This directscortrol to a procedurecalledan interrupt handler. A.t this point, one
of t\r.oeventsoccurs.lf handlingthc int€rrupt takeslittle time andrequiresno system
callsother than certaininterrupt-relatedsystemcalls,the interrupt handlercanprocess
the interrupt itself. Otherwise,the interrupt handlercaninvokean interrupt task,which
deals.i/iththe interrupt. After the interrupt hasbeenservicedby either the interrupt
handleror the interrupttask,controlretuhs to the readyapplic-ation
taskwith highest
qpriority. SeeFigure 1 fo. a graphicrepresentationof this interrupt process.

NucleusUsels Guide

9.1

INTERRUPT

MJ.N,4.GEMENT

INÎERRUPT
INfERRUPT
IABLE

Y E S. . .

. -.

1.
2.
3.
4.
5.
6.

(PlC)rec€ives
ProgÉmmable
ld€rruptComroller
an interupt
PICsignalstheCPU.
CPUacknowledg€s
the interupt.
PICs6ndsth€ interuptnumbertotheCPU.
CPIJobtainsthe inteÍupthandl€rfromthe interuptdescripror
table(lDT).
Controlsentto the irìterupt handler.
Activat6the intsrupt task.

7b.
Returnto the interuptedtask.
R€turnto ih6 irú€rupt€dta6k.
8.
Note: lhe 6olidarows ( l> .) indicalesottwarevectors;
thehollowarows(' --\
vectors.
-'-v ) ind:carel-a.dware

Figure9-1. Intenupt ProcessingModel

9,2 INTERRUPT
MECHANISMS
This sectiondiscusses
the major conceptsof interrupt prccessing:interrupt controllers
andlines,interrupt levels,and the interrupt descriptortable. It alsodiscusses
assigning
inteîrupt levelsto externalsourcesand disablinginterrupts.

9-2

NucleusUserrsGuide

..,-_,/

INTERRUPTMANAGEMENT

9.2.1 InterruptControllersand InterruptLines
Efernal interruptsare passedthroughprogrammableinterrupt controllers(PICs) suchas
the 82594PIC. The iRMX Il OperatingSystemsupportsîhe configurationdescribed
here. Refer to the Exteíded |RMXII InferactíveConfgurationUtîtiEReference
Manuat
for informationon configuringthe operatingsystemto supportthe hardware
configuration.
Under the iRMX II OpemtingSystem,interruptsmustbe funreled though 8259APIG.
In this environment,an individualmasterPIC canmanageinterruptsfrom asmanyas
eight extemalsources.However,the iRMX II OperatingSystemalsosupportsan
expanded(or cascaded)environmentin whichùp to seveninput lines of one masterpIC
are connectedto slavePICS(one input line from the masterPIC mustbe connected
diectly to the systemclock). In a cascadedenvhonment,an input line of a masterPIC
cÍìnconnecteither to an extemalinterrupt or to a slavePIC, but not to both.
Becauseeachof the slavePICScanmanageeightinteÍupts, a cascadedenvftooment
allowsthe operatingsysîemto manageinterrùptsfrom asmanyas56 e\.temalsoùrces
plusîhe systemclock.
If your 80286basedsystemincludcsan 80287NPli you cannotconnectthe NPX to a
PIC. Insteadof usingthe PlC, the NPX usesCPU interrupt traps7 and 16to
mmmunicatedirectlywith the 80286component.Figuîe 9-2illustratesthis situation.

9,2.2 InterruptLevels
The interrupt lines of the masterandslavePICSare associated
with numberscalled
inte[upt levels,asshownin Figure 9-2. An interrupt levelnamesan interrupt line and
indicatesthe priority of the line (in general,rhe lower the number,the higherthe
priority). The interrupt lineson the masterPIC are numberedM0 throughM7. The
interrupt lineson the slavePICSare numberedx0 throughx7 (wherex rangesftom 0 to
I-ower-numberedinterrùpî lineslike M0 or M1 (or linesfrom slavePICSconnectedto
them) havehigherpriority than higher-levellineslike M5 or M6 (or linesfrom slavePICs
connectedto them). Therefore,if two interruptsocculsimultanoously,
the PIC ilforms
the CPU of the higher-prio.ityinteúupt first.
The Nucleusoften disableslow-prio.ity interruptsto allowtasksto servicehigh-priority
interrupts. Refer to the nDisablingInterrupts"sectionof this chapterfor more
information.

NucleusUset's Guide

INTERRUPTMANAGEMENT

Clock is

SLAVE7 PIC

8 0 2 87 N P X

00
of
a2
03
o4
05
06
o7
w-0302

Figùre 9-2. 80286Interrupt Lines

9.2.3 InlerruptDescriptorTable
Whenan interupt occurs,
it triggerstheprocessor
to invokea proccdurewhoscaddrcss
is
listed in a sectionof memorycalledthe interrupt descripto!table (IDT). You enter
interruptaddresses
into theIDT whenconfigùring
the systemor dynamically,
using
SET$INTERRUPT.
Wlen an inteÍruptoccurs,
theprocessor
usesthe entryin the IDT as
a pointer to the interrupt handlingcodeto be executedfor the specificinterrupt. Each
entryin theIDT is a descriptor
thatcontainsthephysicaladdress
of theinterupt
procedure
thatshouldbeprocessed
whenthe speciîied
interruptoccurs.TheIDT is
similar to the GDT ard LDT, exceptthat it is referencedonly asa result of an interupî
or a trap. The IDT maybe locatedanlrurhere
in the memoryof the iRMX II Operating
System.For more detailsaboùtîhe IDT, seethe íAPX 2EóPrcgrammer's
Reference
Manual.

9-4

NucleusUsefs Guide

INTERRUPTMANAGEMENT

Many different eventsmaycausean interrupt. To allow the causeof the interrupt to be
identified,thehardwareassigns
eachinterruptcausea numberandgivesit an entryin the
IDT, The IDT is composedof up to 256entries,numbered0-255.you specirythe
numberof entriesyour applicationneedswhenyou configurethe system.Most userswill
not needmore than 128entries. If, for example,your systemhasonly the 82594pIC
masterwith no 8259APIC slaves,anddoesnot usesoftwareinterruDts.the fhst 64 entîies
are enough.The iRMX II Nucleusdoesnot useentrics128-255.
Theseentriesare
availablefor users.The entriesare allocatedasshownin Table9-1.

EntryNumber
0
1
2

Table9-1. Allocatior of Intenupt Entrles
Description

3
4
5

divideby zero
singlestep(usedby the iSDM monitor)
powerfailure (non-maskable
irterrùpt,usedby the iSDM
monitor)
one-byteinterrupt insbuction(usedby the iSDM monitor)
inteúùpaon overflow
ruo{ime arrayboundserror

undefined opcode

1
8
9
10
11
12
13
14-1,5
1.6
17-55
56-63
64-127
128-255

NPX not present/NPx taskswitch
doublefault
NPX segmentoverun
invalidTSS
segmenrnot present

stackexception
generalprotection
resefved
NPX error
82594PIC master(oúernal interrupts)
8259A?IC slaves(externalinterrupts)
unused

Whenan interrupt occurson anymasteror slavelevel,the processorlooksat the
correspondingentryin the interrupt descriptortable to deteîmineîhe addressof the
prccedureto execute.The procedurethat executesin responseto an inteÍupt is calledan
interrupt handler.
For examplgif a level M2 interrupt occurs,the processorexaminesinterrupt descriptor
58 for the locationof the interrupt handlerfor that lev€I. Thenit traNlers contrcl to thc
hterrupt handler.

NucleusUsefs Guide

9-5

INTERRUPT MANACEMENT

The Nucleusprovidestwo systemcallsfor settingùp the interrùpt descriptortabls
SET$INTERRUrr and RESET$INTERRUPT.SEI$INTERRUPT assignsan inteîrupt
handlerto an interrupt levelby placinga pointer to the first instructionof the handlerin
the apprcpriatedescriptor. RESET$INTERRUPTcancelsthe assignmentof an interrupt
handlerby clearingout the appropriateentryin the interrupt descriptortable. With these
two systemcalls,you cansetup the descriptortableto meetyour needs.

\---l

9.2.4 AssigningInterruptLevelsto ExternalSources
You úust obeythe followingrestrictionswhenassigringintemrpt levelsto extemal
sources:
.

You úust assignthe systemclockto a masterinterrupt level. The levelnumberis a
configurationoption andis describedia theExtendedîRMXII Intercctire
Confguration Utí18 Refercnce
Manu4l.

Whenyou attachan interruptingdeviceto a levelon the masterPIC, you cannotalso
attacha slavePIC to the samelevel. For example,supposethat you physicallyattach
the deviceto level M3. This meansthat ertry 59 (decimal)of the IDT mustcontain
the address
of the interrupthandlerfor the device.It alsomeansthatentries88
through95 (decimal)of the IDT (the slavelevelentrièsthat correspondto master
levelM3) will not be used.

\--l

9.2.5Disabling
Interrupts
Oscasioflallyyou maywant to prevelt interrupt signalsfrom causingan immediate
interrupt. For exaúple,yoù don't wantlow-priority interruptsto interferewith the
servicingof a high-priorityinterrupt. In the iRMX II OpemtingSystem,eachinterrupt
(describedlater), the Nucleusdisables
levelcanbe {!q!!g!. In somecircumstances
Ievels.Taskscanalsodisableandenablelevelsby meansof the DISABLE and ENABLE
systemcalls. However,the masterlevelresered for the systemclockshoùldflot be
disabledor enabled.
If an interrupt signalarrivesat a levelthat is enabled,the operatingsystemtrarsfeÉ
control to the addressmntainedin the IDT entrvthat corresDonds
to the level on which
theinterruptoccurred.If thelevelis disabled,
tÉeinterrupriignalis blockeduntilthe
levelis enabled,at whichîime the signalis recognizedby the CPU. However,if the signal
is no longeremanatingfrom its sourcg it is not recognizedandthe inteÍupt is not
handled.

An interrupt levelcanbe disabledin four ways:
o A taskcanexplicidydisablea specificinterrupt levelby invokingthe DISABLE
systemcall. Later, a taskcanre-enableîhe levellry invokingthe ENABLE systemcall.
.

9-6

A taskcaninvokethe SEI$INTERRUPT systemcall to designaîeitsef asthe
interrupt taskfor a particularinterrupt level. Whenit makesthis designation,the task

NucleusUset'scuide

\_-/

\._-/

INTERRUPTMANAGDMENT

canspecirya fmit to the lùmber of interruptsthat it v/ill queue. If enoughioterrupts
occuron the task'sinterrupt level,the queuecanbepomefull. \ryheneverthis
happens,the operatingsystemauromaticallydisablesthe inîelrupt level until the
queueceasesto be full.
Wherievera task invokesthe RESET$INTERRUPTsystemcall to cancelthe
assignmentof a particularinterrupt handlerto a particularintemrpt level,the
operatingsystemautomatically
disables
thatinterrupllevel.
To providepre-emptivepriority-basedschedulingthe operatingsystemcan
automaticallydisableor re-enablesomeinterrupt levelswhenevera taskbegins
running dependingon the priority of the nevrrunningtaskand the priority of the
previousrunningtask. This allowshigh-prioritytasksto run faster,without hterrupts
from lower-priorityexternaldevices.Table9-2 showsthe correlationbetweenthe
levelsdisabledand the priority of the runningtask.

NOTE

a' A taskthat makessystemcallswheninterupts are disabledshouldnever
usethe PL/M-286 DISABLE statementor the ASM286CLI (clear
interrupt-enableflag) inst.uctionto disableoperatingsysteminterrupts.
Nucleussystemcallsmaycauseinterupts to be enabled.

NucleusUset's Guide

9-7

INTERRUPî

MÀ.NAGEMENT

Table9-2. Interrupt L€velsDisabl€dfor RunnlngTask

34
56
73
910
1&14
15-16
17-18
1920
21-22
23-24
25-26
27-28
2930
31-32
33'34
35-36
39-40
4142
4344
45-46
4744
49-50
51-52
6154
5t56

ú-77
01-77
02-77
0B-77

u-77
05-77
(n-77
07-77
10-77
11-77
12-77
14-77
1 5- 7 7
16-77
20-77
21-77
22-77
23-77
24-77
25-77
26-77
n-77
31-77
32-77
33-77

MO.M7
M1.M7
M1-M7
M1.M7
M1-M7
M1-M7
M1.M7
M1.M7
M1-M7
M2- M7
M2.M7
M2, M7
M2.M7
M2.M7
M2. MI
M2.M7
M2. M7
M3-M7
M3. M7
M3-M7
M3-M7
M3-M7
M3- M7
M3- M7
M3- M7
M4. M7
M4. M7

u-77
s960
61€2
63€r

6$70
71-72
73'74

its - 77
36-77
37-77

M4- M7
M4-M7

40-77
41-77

M4.M7
M5-M7
M5-M7
M 5 .M 7
M 5 -M 7

42-n
43-77
44-77
-.--continùed---

9-8

NùcleusUset's Gulde

INTERRUFTMANAGEMENT

Table9-2. IÍterrupt LevelsDisabledfor RunningTask (confinued)
TaskPriority
Slav6L€vels
77-78
79€0
81€2
4384
&5€6
87€8
8990
91-92
93€4
95€6
97€8
99-100
101-102
10310f
105,'t06
107-108
1@110
111-112
113114
1f5-116
117n18
119120
121-122
123-124
125-t26
127-128
129255

45-77
8.TT
47.TT
50-77
51-ì|7
52-77
53-TT
54-77

57-77
ú-77
61-71
62-77

Disab!€d
Levels
MasterLevels
M5-M7
M5-M7
M5-M7
M5-M7
M6. M7
M6- M7
M6. M7
M6. M7
M6- M7
M6-M7
M6-M7
M6-M7

è4-77

M7
M7

67-77
70-T7
71-77
72- 77
73-77
74-77
75-77
76-77
77
None

M7
M7
None
None
None
None
Non€
None
None

9.3 INTERRUPT
HANDLERS
AND INTERRUPTTASKS
'Whether
an interrùpt handlerservicesan interrupt levelby itself or invokesan inteúupt
task to seryicethe inte..upt dependson two factors:
. The kindsoî systemcirllsneeded
.

The amountof time reqùired

NudeusUser'sGuide

9.9

INTERRUPT MANÀ.GEMENT

Regardingthe first factor,interrupt haÍdlers canmakeonly the ENIER$INTERRUITf,
E)CT$INTERRUPT,GET$LEVEL,DISABLE,andSIGNAI-$INTERRUPTSySIem
calls. If the handlerrequiresother systemcallsto servicethe interrupt, it mustinvokean
interrupt task

\_-/

Regardingthe secondfactor,an interrupt handlershouldalwaysinvokean inteúupt task
unlessthe handlercanserviceinteÍupts quickly. Time is importarÌtbecausean ùrterupt
signaldisablesall interrupts,and theyremaindisableduntil the interrupt handlereither
servicesthe interrupt and exitsor invokesan iriterrupt task. Invokingan interrupt task
allowshigherpriority inte(upts (andill somecases,the samepriodty interrupts)to be
accepted.

9.3.1SettingUpanInterrupt
Handler
Interrupt handlersare generallywritten asPL/M-286 interrupt procedures,but theycan
be written in assemblylanguage.Ifyou useassemblylanguage,you mustsaveand reslore
aUregistervalues,asnotedlater.

Beforean interupt handlercafl servicean interrupt level,a taskmusl invokethe
SEI$INTERRUPT systemcall to bind the handlerandan intem.pt taskto an interrupî
level. SET$INîERRUPT operatesasfollows:
.

One of the SET$INTERRUPTparameters,the inteÚupt$haridlerparameter,
specifiesthe startingaddressof the interrupt handler. SET$INTERRUPTbindsthe
handlerto a levelby placingthis startingaddressinto the IDT at îhe eritry that
mrrespondsto the level. Whenan interrxpt of that leveloccurs,control automatically
traflsiersthroughthe IDT to the handler.
Another pammeterin SET$INTERRUPT,the interrupt$task$flag
paramete.,
detemineswhetheran interrupt taskis associated
with the level. If the
interrupt$task$flagparametercontainsa zero,there is no interrupt îask for the
specifiedlevel. Otherwise,the callingtaskbecomesthe interîùpt taskfo! the level.

If you wantyour interrupt handlerto useanotherdatasegment,you canspeciSthe
selectorofthe interrupthandler's
daîesegment
in the interrupt$handler$ds
parameterof
SEI$INTERRUPT. The irterrupt haridlercanlater load this valueinto the DS register
by callingENTER$INTERRUPT. Interrùpt handlerswdtter in PL/M-286 (including
COMPACT model)havetheir DS registersloadedautomaticallyon invocation.In most
cases,an interrupt handlerand an interrupt taskare compled togetherandsharethe
samedataareas.

9-10

\__,

Nudeùs Usefs Guide

INIERRUPI MANAGEMEM

When an iRMX II application systemstarts runnin& all inteffupt levels are disabled.

Beforetheoperatingsystemenables
aninterruptlevel,a taskmustinvoke
SET$INTERRUPL WhenSET$INTERRUPTbindsan iùterruDthandlerbut not zur
interrupt taskto a level,the operatingsystemenablesthe levelimmediately.However,if
SET$INTERRUPI bhds the handlerandan interrupt taskto the level,the operating
iystem doesnot enablethe leveluntil that taskinvokesthe WAIX$INTERRUPT or
RQE$TIMED$INTERRUPTsystemcall (describedlater)- An inteîrupt taskshouldnot
enableits ownlevelbeforemakingits first call to WAI$INTERRUPT or
RQE$TiMED$INTERRUPT,
A RESET$INTERRUPTsystemcall cancelsthe link betweenan inteffupt level andits
intefiupt handler. Thc call alsodisablesthe speciliedlevel, If there is an inteffupt task
for the level,RESET$INTERRUPTdeletesit. DELETE$TASKdoesnot delete
interrupt tasks.

9.3.2Usingan InterruptHandler
ff an interrupt handlerservicesinterruplsfor a givenlevelwiahoutinvokhg an i errupl
task,the handlermust assumeoneof two forms,dependingon whetherit requhesthe
Nucleusto 6etup the sclcctorof its daîasegment.
If the hterrupt handlerdoesnot needto accsssthe datasegment,or if it canload the DS
registerwith the datasegmentselector,then it shouldperform the followir€ steps:
1,

If in assemblylanguage,saveall registercontents(PL/M doesit lor yoù Ìvhenthe
proc€dureis giventhe INTERRUPT attribute).

Servicethe interrupt.

CalÌEXIT$INTERRUPI. (This sendsan end-of-interruptsignalto the hardware.)

If in assemblylanguage,restoreall regi*er mntents.

Return.

In the rare casewhereyou úay grantto usea specialdatasegm€nt,call
ENTER$INTERRUPTimmediatelyafter step1. An exampleof how to use
E) - î o k . n

C a E A IE S C OM P O S I T E > - T o k o n f o r n è w o b j e c t

T o k è nr ó r r v D è+
List of componenr/

for typ€

..",,

w-0303

Figure 11-1. Creation Sequencefor Composite Objecas

Note thesetwo factswhencreatinga compositeobject:
1.

Its componentqcalledcomponentobjects,are alliRMX tr objects,either Intel- or
user-provided.

No structùreis imposedon coúipositeobjectsof a giver extensionq?e. Two
objectsof the sameextensiontypecanbe completelydifferentin structureor in the
numberof componentsobjectstheycompdse.This featureallowsfor maxunum
flexibility iri the creationof newobjects.

Oncea tlpe managercreatesa newobjecttypeby callingCREATE$EXTENSIO\ that
typemanagerofirs the type. Only the type managercancroat€compositeobjectsof that
type, In addition,whenit createscompositeobjectqthe t ?e managercanrequestthat
the compositeobjectbe sentbackto the typemanagerwhenthe objepthasto be deleted.
(L-atersectionsdescribethis in detail.)

11,3 MANIPULATING
COMPOSITE
OBJECTS
ANDEXTENSION
ryPES
Two systemcallsmanipulateexistingcompositeobjects:INSPEC'I$COMPOSITEand
ALTER$COMPOSITE. INSPECT$COMPOSITE
returnsa list of componenttokerÌsfor
a compositeobject. ALTER$COMPOSIIE replacesa token in the componenllisl of a
compositeobject,with either anothe.token or a null.

rt-2

NucleusUseis Guide

TYPEMANAGERS

11.4 DELETING
COMPOSITE
OBJECTSAND EXTENSION
TYPES
Two systeú callsdeletecompositeobjects: DELETE$COMpOSITEand
DELETE$EXTENSION. DELETE$COMPOSITEdeletesa particularcompositeobject
(bùt not its components).DEiETE$EXTENSION deletesa specfied eytensiontype,and
either deletesall compositesof that typeor sendsthem to a deletionmailbox,in which
casethe typemanagermustdeletethem.
A thid systemcall, DELETE$JO8,alsodeletescompositeobjectsasa part of its
processing.Although DELBTE$JOBcannotdeleteextensionq?es (iî returnsa.l
exceptioncodeif thejob contahs anyextensionobjects),it candeletecompositesor send
them to deletionmailboxeswheretheir g?e managersdeletethem.
The deletion$malboxparameterin the CREATE$EXTENSIONsystemcall dctcrmincs
whetherDELETE$EXTENSIONandDELETE$JOBdeletecompositeobjectsor send
themto deletionmailboxesThisparameter
hastwooptions:
If you specirySELECTOR$OF(NIL)for the pa.ameter,then
DELETE$EXTENSIONandDELETE$JOBassumeall responsibiliryfor deleting
compositeobjects.The t,?e managerplaysno part in the deletionprocess.h this
case, you can skip the ne\-t three sections of this chapter.

If you speci| a mailboxtokenfor the paramerer,rhenDELETESEXTENSIONaùd
DELETE$JOBsendtokensfor all composireobjectsof the indicaredrypero rhe
mailbox. The typemanageris thenresponsiblefor deletingthe compositeobje.ts.
Two conditionsmustbe met beforethe typemanagerreceivestokensfor composite
objectsvia the deletionmafbox:
The qpe manager,.rhenit callsCREATE$EXTENSION,mustfill in the
deletion$mailbox
parameterwith a toke! for a mailbox.
A taskmustcall DELETE$EXTENSIONor DELETE$JOB.
The followingsectionsdescribethe tt?e manager'sresponsibilitiesin more detail.

l1 .4.1 TypeManagerResponsibilities
DuringDELETE$JOB
Whena taskcallsDELETE$JOB,the Nucleusnormallydeleteseveryobjectin thejob.
However,if thejob contaiN a compositoobjectwhoseeÀlensionhasa d€l€tionmailboó
the Nucleussendsthe tokerifor the compositeobjectto the deletionmailbox. The
Nucleùsthenwaitsuntil the ty?ernanagercals DELETE$COMPOSIIE before
continuingthe d€letionprccess.
The type managerhasthe followingresponsibilìtiesfor servicingthe deletionmailbox:
1.

It mùst wait at the deletion mailbox to receive the tokens for the obiects to be

deleted.

Nudeus Uset's Guide

11.3

TYPE MÀN,{GERS

It mustperform anyspecialprocessingrequiredto deletethe compositeobject. For
example,it mightwant to wait ù.ltil all taskshavestoppedusingthe composite.

It hasthe option of deletingthosecomponentobjectsnot containedin the job being
deleted. It cannot,however,deleteanyobjectscontainedin the job beingdeletedor
it will incur an exceptionalcondition. (This is not a p.oblembe4ausethe objectsin
thejob beingdeletedwill automaticallybe deletedduringthe DELETE$JOBcall.)

It shouldcaIIDELETE$COMPOSITE,whichdeletesthe compositeobject(but not
the componentobjects)and informsthe Nucleusthat the tlpe managerhasfinished
processingthat deletesthe compositeobject. After the typemanager
the spe.cial
cals DELETE$COMPOSITE,the Nucleusresumesthe DELETE$JOBproce.ssing.

The tlpe managermustcall DELETE$COMPOSmEeachtime the NucleusseÍds a
tokenfor a compositeobjectto the deletionmailboxbecauseDELETE$COMPOSITE
retumscont.ol to the Nucleus.If the q?e managerfails to call DELETE$COMPOSITE,
the DELETE$JOBsystemcall will not finish processingFigure 11-2illushatesthe type
manage/sinvolvementin the DDLETE$JOBprocess.

Figùr€ 11-2. TlTe ManagerInyolyeúentin DELETE$JOB

11-4

NucleusUsefs Guide

TYPEMANAGERS

Note that the typemanageris not requùedto deleteall componentobje{ts. ln the course
ofDELETE$JOB, the NucleusdeletesanyNucleusobjectsin thejob. The Nucleussends
the tokensfor anyI/O System,ExtendedI/O Sysrem,or Huma[ Inrerface(all three are
OSextensions)objectsto theh respectivedeletionmailboxes,wherethe subsystems
themselvesd€letethe objects.The Nucleusscndsthe tokensfor all other composite
objectsto their own deletionmailboxes,wheretheir typemanagenare responsiblefor
deletion. Therefore,all the compoùentobjectsare eventuallydeleted,providedthey are
in the job beingdeleted.

11,4,2TypeManager
Responsibilities
DuringDELETE$EXTENSION
A taskcancall DELETE$EXTENSIONto deletean extensiontype. This is usefulwhen
the licenseto createcompositeobjectsof a givenextensiority?eis no longerneeded.
Whena taskcallsDELETE$EXTENSIONard the extensionhasa deletionmailbo&the
Nucleùssendsîhe tokensfor all compositeobjectsof that extensiontlpe to the deletion
mailbox. After sendinga token for an objectto the deletionmailbox,the Nucleuswaits
until the typemanagercals DELETE$COMPOSITEbeforesendingthe nextc.mposite.
The type managerhasresponsibilitiesduringDELETE$EXIENSION similar îo
DELETE$JOB. First, it mustwait at the deletionmailboxfor the objects'tokens. Th€n,
it musthandleanyspecialprocessingnecessary
to deletethe object. Finally,it mustcall
DELETE$COMPOSIIE to deletethe composite.As with DELETE$JOB,the gpe
managermustcall DELETE$COMPOSIIE for eachtoken it receivesat the deletion
mailbox-If it doesnot do this,the DEI-ETE$F-XTENSTON
systemcallwill not linish
processing,
However,unlike DELETE$JOBprocessing,
the t'?e managerhasthe choiceduring
DELETE$EXTENSIONofwhether or not to deleteindividualcompolent objects.If it
wishesthe componentobjectsto be deleted,the ttpe managermust explicitlydeletethese
obje.ts. Unlike DELETE$JOB,DELETE$EXTENSIONdoesnot deleteanycomponent
objects.

l1 .4.3 Deletionof NestedCompositès
Sincea compositeobjectcaocontainobj€clsof anykind, sr.rme
of its @mponentobject$
maybe compositeobjectsthemselves.This cancauseproblemsfor typemanagerswhen
they deletethe compositeobjectsif the t,?e managerfor anyof the compositeobjects
dependson the eústenceof anyof the other compositeobjectsto completeits processing.
For example,supposeobjectsA andB are compositesin the samejob. Theyhave
different extensiontypes,andB is a componenîof A. Eachcompositehasa qpe manager
that performsspecialcleanupfunctionsbeforeit candeletethe correspondingcomposite.
If neither type managerrequiresinformationcontainedin the other compositeto perform
its specialprocessingthe deletionprocesscanproceedwithout difficulty.

NucleusUset's Guide

1l-5

TI?E

MANAGERS

However,if the t)?e managerfor compositeA reqùiressomeinformationcontai[ed in
compositeB to completeits processingthe deletionprocessbecomesmore complex.For
this deletionschemeto work, you mustguaranteethat composiîeA will be deletedbefore
compositeB. Thus,you musîknowthe order in whichthe DELETE$JOBdeletesobjects
and sendscompositesto deletionmailboxes,sothat you cansetup your composites
correctly.

\-,

DELETE$JOBdeletescompositeobjectsbeforeit deletesnon-compositeobjerts. It
deletescompositeobjeatson a last-in-li$t-out basis;that is, in the reverseorder fiom
\À/hichtheywere created.Therefore,a typemanagercandependon receivingthe tokens
for compositeobjectsthat it createsbeforethe Nucleusdeletesthe componentobjects
containedin them. The only exceptionis whena composite(compositeA) is cleated
beforeanothercomposite
(composite
B), andcomposite
B is insertedasa component
into compositeA usingAITER$COMPOSITE. In this case,compositeB will be deleted
first, andthe t)?e managerof compositeA cannotrely on the existenceof compositeB
whenit receivescompositeA for deletion.

11.5 WRITING
ATYPEMANAGER
A type managerconsistsof two parts:
The initialization part createsthe typeandoptionallycreatesa deletiol mailboxto
whichthe systemcansendtokensfor objects*hendeletingeitherjobsor theqpc
itself.
The servicepart providessystemcallssotaskscanqeate and manipulateobjectsof
the type.
Becausethe initialization phasemustbe completedbeforeanytask attemptsto obtain
tokensfor objects,the initialization part shouldbe written asa taskthat executeseaù in
the life of the system.To ensureearlyexecution,the taskshouldbe part of the
initialization taskofa firstlevel use.job in thejob tree. Rlelerto the íRMXII Interactive
ConfgwatíonUtilityReference
manualfor informationconcerningiirst-leveljobs.
The servicepart of the type manageris written asan operatingsystemexterision.(Refer
to Chapter10ior more information.)
The bestwayto learn abouttlpe managersis to studyan example.The followingexample
presents
the mainpartsof a q?e manîgerfor ringbuffers.

l1-6

NùcleusUset's Guide

TYPEMANAGERS

11.6 EXAMPLE-.4
RINGBUFFER
MANAGER
This exaúpleshowsthc mosteducationalportionsof a ring buffer managcr,It alsoserves
to illustrate the varioùsparts of an operatingsystemextension.Be advised,however,that
the exampleis inmmpleteand shouldbe imitatedwith dissetion. In particulaqthe
examplehasthe followingshortcomings:
The issueof exceptiol handlingis nof addressed.Clearlythe codesupportinga
systemcall shouldexamineeachinvocatiorifor validity,but, for brevity,the ring buffer
exampledoesnot do this.
Thereare no saleguardsagainstpartial creationof an object. Whenceating a
compositeobject,a typemanagermustfust createthe componentsof the object.
Occasionally,after oeating someof the components,the managermight be unableto
cr€atethe others. A type managershouldbe ableto recoverfrom this situatioq
usuallyby deletingthe componentsaheadycreatedaridreturriingan exceptioncodeto
the caller. the example,againfor bre',ity, doesnot do this
The entry routine doesnot checkthe entry codefor validitr.
The potentialfor problemswith deletionis ignored. For this reason,you should
imaginethat the envhonmentof the exampleis constrainedin at leasttwo ways. Fftst,
only one taskwill eveîîry to deletea ring buffer and,whenit doestry, no other task
will be usingthat buffer. Second,whena job contairÌíriga taskthat createda ring
bulfer is deleted,no tasksin otheîjobs are usingthat ring buffer.
'

The examplelas beendesk-checked,
but the examplehasriot actuallybeeritested.
A ring buffer is a blockof memoryin whichbltes of dataare placedat successively
higher
addresses.Interspersedwith byte insertionsare b''te removals,vr'iththe restdctionthat
the bytebeingremovedmustahvaysbe the bytethat hasbeenifl the buffer foÌ the longest
time. Thus,data entersandleavesa ring buffer in a FIFO manner. Ringbuffersare so
namedbecausethe lowestaddresslogicallyfollowsthe hìghestaddress.That is, if the last
byte placedin (or retrievedfrom) the buffer is at its highestaddress,then the nextbj/teto
be placedin it (or retrievedfrom it) is at the lowestaddress.As dataentersandleaves
the buffer, the portion containingdata"runsÍaroundthe ring, with the pointer to the last
byte out 'bhasing"the pointer to the last b,'tein. Figure 11-3illùstratesthese
characteristics.

NucleùsUsefs Guide

tl-7

TYPE M.{NAGERS

figure ll-3. A RingB!fier

The main (service)part of the exampleconsistsof four proceduret: CREATE_RING
BUFFER, DELETE_RING_BUFFER,
PUT_BYTE,and GET_BYTE.The last two
prcceduresare for placinga characterin a ring buffer and for retrievinga character,
resDectivelv.

1t-8

NucleusUset's Guide

IYPE MANAGERS

/*************************:t*:t**********it*********************************

* NOTE: The following commonlíleral
(COMUON.LÌT)is
file
* in each of thc PLIM-286 porrions of the exdple.
*********************x*x************************************************//

included

DECLARETOKEN
]-ITERAILY 'SEI-ECTOR';
DECIARE forever
LITERALLY ,ltHlLE 1,;
DECIAREindeftnitely
LITERALLY.oFFFFfl,;
DECIAREASTR$STRUC
LIÎEMLLY'STRUCÎ'RE(

num$slors
woRD,
numsco[ponents lrIoRD,
seg
TOKEN,
enpry9cr
ToKEN,
full$ct
TOKEN),;
DECIAREPOINÎER$STRUC LIÎERALLY ' STRUCTURE(
offset
WORD,
selector
SELECTOR)'
;
DECI,ARESEGMENT9STRUCLITERAI,LY ' STRÙCI'TIRE
(
síze
IùORD,
head
t{oRD,
tail
WoRD,
buffer(1)
sYIE)' ;

11.6.1 Initialization
The initialization createsa regionto protectdatain ring buffersfrom beingmanipulated
by more than one taskat a time. This part of the OS extensionalsocreatesthe requted
exlensiongpe, qeates a deletionmailbo! andthenwaitsat the deletionmailbox. The
OS e\tensioncall-gatesare establishedduringconfiguration.For this example,they are
GDT slots440H,441H.44211and 443Il' Cod€lor the iniriirlizarionircludes the
following:
LIT) ;
$INCLUDE(| Ix: COI'ÍMON.

NùcleusUset's Guide

Declares

conrnon literals

1t-9

TYPE N,TANACERS

RING$BUFFER$MANAGER:
PROCEDT-EE
EXTERNAI;
TND R]NCSBUFFER$MANACER
:
DEoLARErtng$buffer$Lype
TOKENpuBllc;
DECI^AREring$buffer$iegion
TOKENPUBLÍC;
R]NC-BÙFFER
INIT:
PROCEDÙRÈ;
DECI,AREdelete$obj ecr
ToREN;
DECI,AREexceprion
UORD;
DECIARE ftfo
rITERALLY ,0' ;
DECLARErb$code
ITTnRALLY ,8000H' ;
DECLAREdeletion$mbox
TOKEN;
DECURE response$mbox
TOKEN;
= RQ$CREATEgREGÌoN
ríng$buffer$region
(
fifo,
Gexception);
= RQ$CREATE$MAILBOX
deletion$nbox
(
fifo,
@exception);
ring$buf fer$type-RQgCREATEgEXTENSION(
rb$code,
deletion$mbox,
@èxception);
CAI,L RQ$END$INIT$TASK;
DO |OREVER;
: RQ$RECETVEgMESSACE
delete$object
(
deletiongnbox,
indefínite1y,
@response$mbox
Gexceptton);

\--l

\---l

/:t*****!t****:t*****rt*************rt******************)t***:t*****************
* lf desired, delete the conponents of the conposite objecc.
They are *
* not automacically
delered Íhen DELETE$EXTENSIoNis called.
See rhe *
* DELETE$RINGSBUFFER
procedure, shown fater,
*
for the code that does
* this.
*:!*****************:t*)t***********)t*)r**********:t+:!***********************/
CALI, Rq$DELETE$COMPOSITE
(
delece$object,
Gexcepcion);
END;
/*' FOREVSR*/
END RING.BUFFER-INIT;

1l-10

NucleusUse s Guide

\--l

TYPEMANAGERS

11.6.2TheInterface
Library
The user interface library consistsof four small procedures, ofle for each of the system
calls provided by the operating systemqtension. The library supports application code
writteri in the PL/M-286 I-ARGE model. If a different model had been used for
compiling the application code, these interface procedures would be slightly different,
reflectiry the fact that, when making procedùre calls in othef modelq the stack is used
differendy than in the LARGE model. The interface procedures are as follows:
CREATERB

PROC FAR
PÙBLIC CREATERB
EXÎRN GATE-440: FAR
PUSH

M0v

CREATERB

PUSH
CALL
POP
RET
ENDP

DELETERB

PROC

buffer

BP
B P ,S P
BP+6
; paraneter--the size of the ring buffer
GATE_440
; calt the Os-exÈension vie a call-gare
BP
2

FAR

PUBLIC DELETERB
EXTRN CÀTE_441.:
FAR
PUSH

M0v

DELETERS
CETRBI"IE

PUSH
CALL
POP
RET
ENDP
PROC
?UBLIC
EXTRN

FAR
CEÎR3fTE
CATE442: FAR

PUSH

t{ov

GETRBYTE
PUTRBI'ÎE

BP
BP,SP
BP+6
t paraneter--the rlng buffer to delete
GATE-441
wia a call
gate
; call the os-extension
B?
2

PUSH
CALL
POP
RET
ENDP
?ROC
PUBL]C
EXTRN

NucleùsUset's Guide

8?+6
buffer
to read fron
; paraneter--ring
cÀ.TE_442
; call thè Os-éxtension via a call-gate
BP

2
FAR
PUTRS\"IE
GATE_443: FAR

11-11

TYPE MANAGERS

PUTRBYÎE

PUSH
MOV
PUSH
PÙSl{
CALL
POP
RXT
END?

BP
BP,SP
BP+8
ÀP+6
CAîE 443
BP
4

\-/
char:acter to nr:ite
; paraneter:--the
buffer to grfte
to
; pataneter--ring
; call Os-extenslon via a call-sate

These interface proc€dures correspond to a set of external procedure dealaratior$ iri the

applicationPL/M-286 code:
CREATERB: PROCEDITRE(SIZe)
DECI,AREsize
END CREATIRB;

ToKENEXTERNAL;
l{oRD;

( ring$buffer$token)
DELETERB: IROCEDI'RE
DECLAREring$buffer$token
T0KEN;
END DELETERS;
GETRBBYTE: PRoCEDURE(riîgqbuffer$token)
DECLAREring$bufferstoken
TOKEN;
END GETRBBYIE;

PUTRBBYTE: PROCEDURE(Chat,ling$buffer$token)
DECI,AREchar
BYTE;
DECI,ARErtng$buffer$tokèn
ToKEN;
END PUTRBBYTE;

Lt-12

\--"

EXTERNAL;

BYTE EXTERNAL;

EXTERNAL;
\" -'

NucleusUset's Guide

TYPEMANAGERS

11.6.3 TheCreateRingBufferProcedure
The solefunctionof the CREATE-RING_BUFFERprocedureis to createa ring buffer
for the calÌingtask andto return to the taska token for the compositering buffer object.
Eachring buffer consistsof three objects: a segmentandtwo semaphotes.The
supportingdata structure,reqùiredby the operatingsystemfor callsto
CREATE$COMPOSITEandINSPECI$COMPOSITE,hasthe fotlowingfive fields:
The numberof slotsavailablefor tokensin the followinglist of componentobject
tokens, B€causering buffersare composedof three objectsand no comporrents
will
be added,the numberof slotsis setto three.
The numberof componentobjectsactuallyin the compositeobject. In this casg the
numbeaof componentsis three.
A token for a segment.The segrnentcontainsthe ring buffer. The first word in the
segmentcontainsthe sizeof the actualring buffer. The secondword of the segmentis
a pointer to the mostrecentlyenteredb1'tein the buffer. The third word poiùts to the
oldestblte in thebuffer. Theremainderof thesegmenr
is usedasrhebuiferitself,
Note that, in the program,a stucture reflectingthe intendedbreakdownof the
segmentis superimposed
on the segmeùt.
A tokenfor a semaphore.This semaphoreis usedto keeptrack of the numberof
vacanciesin the drg buffer. Thus,it is initialized to the sizeof the buftér.
A token for a semaphore.This semaphoreis usedto keeptrack of the numberof
occupiedbytesin the riry buffer. Thus,it is initia$zedto zerc.
The CREA'IE_RING-BUFFERroutine createsthe componentsof the compositering
bùffer object,initiatizesthe appropdatefields,then createsthe compositeobject,as
follows:

NucleusUsefs Guide

l1-13

TYPE MANAGERS

i I*: COMMoN,
LIî) ;
$INCLUDE(
DECLARE
ríng$buffergcype

/* Deelares connon literé1s
TOKENEXTERNAL;

:t/

CREATE.RINC-BUFFER
:
(stze) ToKENPUBLICREENTRANT;
PRoCEDIIRE
DECI,ARE
tloRD
size
DECI,ARE
seg$prr
POINTER;
DECLAREptT$struc
POINTER$STRUCA.T(Gseg$ptr);
DECI-ARE
astr:
AsTR$sTRUc;
DECIAREsetnrent
SEGMENT$STRUC
BASEDseg$ptr;
DECI,ARE
exception
1,I0RD,
DECLARETtng$buffer
TOKEN;
prioricy
DECLARE
LITERALIY'1';
astr.n\ndslots - 3;
astr. num$conponents- 3;
(
astr. seg - RQ$CREATE$SEGMENT
slze+6,
Gexception);
astr. enpty$ct : RQ$CREATE$SEMPHoRE
(
priority,
Gexception);
(
astr. full$ct : RQ$CREATE$SEMAPH0RE
0,
priority,
@excepcion);
ptr$struc.base - astr. seg;
ptrqstluc. offsec = 0;
cadnèhi

ci za

cizo.

segnent.head = -1;
segnenc. tail - 0;
: RQOCREAîE$CoMPoSITE
Ein8$buffer
(
vl ndq}|,,ffarAtlh.

@astr,
@excepcion);
REî|RN ting$buffer;
END CREATE.RING-BUFFER;
The segment.headvariable is set to -1 becauscthc PUT_BYTE procedure (shown later)
advancesthis pointer bgÍOlg placing a character ifl rhe buffer,

t7-74

NucleusUset'sGuide

ÎYPE MANAGERS

11.6.4 TheDeleteRingBufferProcedure
DELETE-RING-BUFFER, which can be called by any task, deletes a ring buffer.

$INCLUDE(:Fx:C0l'fMON.LlT); /* Declares corìnon literals
DECIARE rlng$buffer$tne
ToKEN EXTERNAL;

DELETE_RING-BUFFER
I
PROCEDURE(ring$buffer$token)
REENTR-ANT
PùBLlc ;
DECI-ARErlng$buffer$token
BASEDToKEN;
DECLARI astr
ASTR$STRUC;
DECI-AREexceptlon
WoRD;
astf,. nungslots - 3;
(
CALL RQ$INSPECT$COMPOSITE
rinoSh,,f
tl

fèrSl.lha

ndqh,'ffaYqi^Lan

@astr, @exception):
CALL RQ$DELETEICOMPOSITE
(
rlng$bufferS cype,
'i

hdqÀ"fférqr^L--

@€xception) ;
(
CALL RQ$DELETE$SEGMENT
astr. seg,
@exception);
(
CATL RQ$DELETE$SEMAPIIORE
astr. enpty$ct,
Gexceptlon);
(
CALL RQ$DEIETE$SEMAPHORE
ast!.fu11$cc,
Gexcèption);
END DELETE-RING-BUFFER
;

11.6.5ThePutByteProcedure
PUT_BYTEplacesa characterin the buffer by advanciúgthe pointer to the front of the
buîfer then placingthe characterin the bytebeingpointedto.

NucleusUserrsGulde

1I-15

TYPE MANAGERS

$INCLUDE(:Fx:COÌ4MoN.LIT);
/* Declares connon literals
DECL{RErtng9buffer$type
ToRENEXTERNAI;
DECI,ARE
ring$bufferqreglon
ToKENEXîERNAL;

PUT-BYTE:
PROCEDURE(Char,
ring$buffer$token) REENîRANT
PUBLIC;
DECIAREring$buffer$token
ToKEN,
char
BYIE;
DECIAREsize
woI{D;
DECLARE
Éeg$pt!
PoINTER;
DECLAREptT$struc
PoINîER9STRUCAT(@sèg$ptr);
DECLARE
astr
ASTR$STRUC;
DECIAREsegnenc
SECMENT$STRUC
BASEDseg$ptr;
DECIAREexception
I.IORD,
DECIAREuntrs$1eft
Ì10RD,
,
/FJfl.286/DW|O
/pt-rf/MB2lTNTRO
to attachto the dtectory containingthe exampleprograrns.To geoelate tlìe execùtable
modulesfor theseexamplesrype:
SUBMIT COMPILE

Thesetwo commandsmustbe q,pedin on both hostterminals,assumingthat eachhost
hasits owndisk.
Most of the examplesusean externalfle calledDCOM.EXT and a literal file called
DCOM.LIT. Both of thesefiles are presentedat the end of this chapter.
The examplesin this chapterare presentedin an order similar to their usein a real
system.The examplesstepyou throughthe followingconcepts;
1.

Scannlngthe systemto determiflewhatboardsare in the system.This example
runsindependendyof all the other modùles.

2. Crcatinga datatraúspof protocolport to usein message
passing.This exampleruns
indeDendendv
of all îhe other modules.

12-16

NucleusUsefs Guide

\v/

EXTENDEDiRMX@II MULTIBUS@N SYSTEMS

3, S€ndingan RSYPmessageto anotherboardandwaitinglor a reply. This module
mustbe run with example4 io this list or with example7 in this list.
4. Arcwerlng an RSVPmessage
from the receivingboard. This modulemustbe run with
example3 in this list.
5. Sendinga datachain message.This examplemustbe run with example6 in this list.
6. Receivlnga daúachaln messate.This examplemustbe run ì/rithexample5 in this list.
7. Sendinga fragmentedmessage.This exampl€mustbe run with example3 in this list.
The exampleslisted abovemakeceÍain assumptions
aboutthe locationsof the host
boardsin îhe MULTTBUSII ststemthat theyrun on. The Figure 12-4showsthe required
physicallocationsof the hostboards(agents)in the system.

(Chassisnot to scale)

M e m o r yF o r
H o s ti n S l o t5
H O S TB O A R D
I N S L O T5

M e m o r vF o r
H o s t i n - S l o t1
H O S TB O A R D
I N S L O T1
È

C S MB o a r d

Figure l2-4. PhysicalLocationof Boardsin the Example

NucleusUset's Guide

t2-17

EXTENDED iRMX@II MÙLTIBUS@ II SYSTEMS

The MULTIBUS II examplesdtectory alsocontainsa larger examplethat is not shownin
this chapter. This exampleimplem€ttsa "nameserver",a progam that permitsthe
dynamiccatalogingof all ports oeated in a system.A later s€ctionof this chapter
discusses
thisexample.

\--,,.

'12.5.6.1InlerconnectSpaceExample
Beforepassingmessages
betweenagenîs(boards)ir your systemyou rieedto determine
what boardsare in your systemandthe message
addresses
for the boards(host$idor
cardslotnumberfor boardson the iPSBbus.) You may alsoneedto read or write the
contentsof a particularinterconnectiegister. Writing a boardscannertask allowsyou to
dynamicallydeterminehostIDs, boardg?e, andmultiple occurrences(instances)of a
boaÌd type.
This s€ctionpres€ntsan €xampleof g€ttingthe iotercorìnectinforination for an entire
system.The examplepedormsthe board scan,gettingthe slot numberandboard typeof
each board in the system and places the information into an array of structures called

sys_map.Whenthe boardscanis completgsys_mapis displayedon the consolesoeen.
Figure 12-5presentsa board-scanning
algorithm. The "reads"in the Figure 12-5. Board
ScanningAlgorithm refer to the RQ$GET$INTERCONNECTsystemcall. For a mapor
templateof a particularboard'sinterconnectregisters,refer to the board'shardware
referencemanual.

FoR i = 0 to number of slots minus 1
DO;
Read board i's vendor ID register;
IF vendor ID c 0 then
DO;
Read board i's class and subclass ID retisters
,/* Deternine board t)?e */
WriLe Ehe board informatíon ínto the syslem map
END;
ELSE;
Write 'enpty'
into the sys_nàp for thè sloc nuber
END;
Cet lD of loca1 hosc
END;
FoR i - 0 to n(lrnber of slots ninus 1
DO:
Print slot numbers and board È)?es to console screen
END;

Figue l2-5. BoardScanningAgorithm

t2-18

NucleusUset's Guide

EXTENDEDIRMX@II MULTIBUS@tr SYSTEMS

In the fourth line of the board scarineralgorithm,a vendorID of 0 (for iPSBhostsonly)
indicatesthat either the boardwasmanufactuîedby a non-licensed
vendoror the cardslot
is empty. Ifyou are alsoscanningthe iLBX II bus,replacethe 0 with oFFFFH.
To run the boardscannerexampletype:
rc

NucleusUset's Guide

t2-19

EXTENDED iRMI(@ II MI]LTIBUS@ II SYSIEMS

The followingfigure is an implementationof the board scanneralgorithm.

9title('1c
SeonDacc

- scan interconnect

space and prlnt

r0ap of systen, )

IN1EL CORPORATION
PROPR]EÎARYINFORMATION
Ittis software is supplled under Che tenns of a
license agreement or nondísclosure
agreenent nith
lnCel Corporacion and nay not be copieat or disclosed
except ln accordance lrith the terns of that agreenent.
Copyright Intel
al1

ríohic

Corporation

1987, 1988

rèaan'a.l

*
*
*
*
*
*
*

For lntel
custoDels licensed for the lRlO{ II operatíng
System under an Intè1 Software License Agreenent, rhis source code and
object code deríved therefrorn are licensed for use on a stngle central
processing unit for inte1:nal use on1y.
Necessary backup copies and
roulciple users are permitted.
Object Code derived fron rhis source code
ls a Class I sofù,/ale produc! under the Intel
Sofc\rare License Agreenent
and is subject to the terns and condirions
of rhar agreemenr

*
:"

Fol the ríght to make incorporacions,
or ro transfer
third parties,
contact Intel corporatíon.

this

soft\rare

\-7

/********************:t************:k***********rt****:t*:t:t****************:trt**/
/********rt*rf************rt*rf***********************************)t*******
* MODULENAI'fE: lcscan
*' DESCRIPTIoN: Scan the iPSB backplane,
Record each board insrancè and
*
slot nunìber in a system roap. Cet local host slot number
*
and id and record in systen nap. print systen nap on console.

****************,***rl***********rt*******************************!t******/
ic:

DO;

$include (/rnx2 86/inclrmxptn. ext )
$include (/rnx2 86/lnc/error. 1ít)
$include (err. ext)
Figùre t2-6. Irnplemenfation of a Board Scanner (continued)

t2-20

NucleusUset's Guide

\.-,-/

EXTENDDDiRMX@II MULTIBUS@II SYSTEMS

DECTÀRE

llterals

MAXSmTS
LITERALIY
VENDoRIDREG LITERALLY
BoARDIDREG
LITERALLY
BOARDIDI,EN
LITERALLY
BUFLEN
LITEMLLY
I,oCAIIIoST
LITERATLY
PSBCoNTROLRECI,ITERALLY
PSBSLOTIDOFF LITEMLLY
NoEXCBPT
LITERALLY
RECNoTFOLND LITERALLY

'20',
'00',
'02H'
,
'10',
,11,,
'31',
tO6H,
,
,02H'
,
'0',
,oFFH,.

/* araxinum nìrnlber of slots */
.reg */
,/* 1o\d byre of vendoi 1d
/* regiscer offsec of boàrd id */
./* nurnber of byres ín loard td */
,/* length of boatd id rrox string */
*/
/* selects local host interconnect
*/
record valuè
/* psb control
of slor id reg ín psb conrrol rec *
/* offset
,/* no exception handling by systen */
/* indicates
fnterconnecr
record not found *

LITÈRALLY , STRUCIURE(

map_struc

Id(BUFLEN) BYTE,
slot,nulr
BYTE)' ;
DECI-ARE
c o n _ t a b ( 1 6 )b y t e I N I T I A L ( ' 0 ' , '
qcrlhil

i1a I ' fi nd

,'s' ,'6' ,,7, ,'8, ,
'9"' 4"' R"'C'.'D"'E"'F.)

zó^^//ì,\

* PROCNAME: find_record
* DESCRIPTION:
*
Searches through thè interconnect
space of rhe specified
board
*
(s1ot_nurber)
until
eíther the record type passed is found or the
x
EOT (end of tenpfate)
record is fourd.
If the record ls found,
*
then its record type and offset are returned.
If the EOT record
*
is found, then oFFH is r€turned.
* CAIL:
record found :
* lNPfIs:
slotlnumber
*
recoid_type
* RETURNS:tecord_found
* oUTPUTS: record_offset

record ( slot_nunber,
j
lecord_t]?e,
rec_offse!_pÈr)
Bltf containing
slor number ól board
BYTE conuaínin! record tJ.pe Lo find
byte indicating
I'hettrer record was found
contains oFFlt (EoT record type) if record nor found)
prr
PoINîER to WORDoffser of record found

find

***rt*rl*:l************rV*r!*:t********:t*****rt*******************************:t****/

Figure 12-6. Implementationofa BoardScanner(continued)

Nucleus Use/s Guide

12.21

EXTENDED iRMXó II MIJLTIBUSo

( sloc_nunbe!, record_t)rye, rec_offset_ptr)
PRoCEDURE

find_record:
REENTRANT;

DECI-ARE
slot_nunlber
record_type
fó^

SYSTEMS

SYTE?uBLIc \-,,

BYTE,
BYTE,

^€fcAi

rec_offset
rèóord_found
status

BASEDrec_offsec_pr!woRD,
B\1tE,
woRD;

DECIARE
EOî_REC
LITERAtLif 'oFl'll',
HDRRECLENGTH
LîTERAI-LY '2OH' ,
RECLENREC LITERAI-LY '1';
*
*

/*
/*
/*

end of template ]recotd */
nunber of registers
1n header ì.ec */
\--l
*/
recorà length reglster

Get record type for each lecord past che header
record untíl the specified record ls found

: HDRRECI-ENGTH;
rec_offset
record_found - rq$get$ tnterconnect ( slot_nunber, rec_offset,
CALL error$check (100, srarus)
DO IrttILE (record_founal o rècord_t)rpe) AND (record-found
o
*
*

Gstatus);
EOT-REC);

Get offset
fof next recorat by addÍng length of curreDt lecord
(add 2 to accounlr for type and length
to prevíous record offset

rec_offsef:

= rec_offset

+ 2 + tq$get$interconnect(s1ot_nunber,
rec_offser
+ RECLENREC
,
Gstatus);
CALI- errorqcheck ( llo , status);
recold_found = rq$get$ interconnect ( slot_number, rec_offset,
CALL error$check ( 120 , status);
END;

\--l
Gstatus);

RETURN(record_f ound) ;
END find_record;

Figue 12-6, Implementationof a BoardScanner(continued)

12-22

\--7

NucleusUset's Guide

EXTENDED iRMX@ II MULTBUS@ N SYSTEMS

$subtitle ( 'out_byte - prlnt

a byce on the console,)

/*********!t*rt*****:!*:!*:!*****!t**********************************:!tr*:t**

* pRoC NAME: out_byte
* DESCRIPTIoN: tirlte

the hex repres€ntacion

of hex byte

to the console.

* CALL| CALL out_byte (hex_byte)
* INPUT: hex_byce

- byte whose hex value

to be printed

* CLOBALS:
*
*****************x************>t*:t************************************/
^

our byre:

procedure (hex_byce) publíc:

DECI,ARE
hex_byte
hex_buf(3)
cur_byte
status

BYTE,
BYTE,
BYTE,
tloRD;

cuÌ_byte - shr (hex_byre, 4);
hex_buf(o) - 2;
hex_buf( 1) : con_tab (cur_byce) ;
cur_byte - hex,byte AND oFH;
hex_buf( 2) - con_reb (cur_byte) ;
call rqc$send$eo$response(NIL, 0 , Ghex_buf,@srarus) .
END ouc_byre;
*' ! é- Pr

- nrinr
/**********:l*:!***:l**,***tr*********)t*)t*****rt*************t<*)t*t<****rt*:t**
*
* PROCNAME: print_nap
*
* ABSTRACT: Write systen map to console
PL LrrL

* CAI-L: CALL printmap ( sys_map_ptr ) ;
* INPUT: sys_map_pcr - pointei
X GI,OBALS:
*
* CALLS: rqcssendseo$response,

to systeú nap

out_byte

**************************)t******)t*)t*)t*)t*****************************/

Figure 12-6. IDplementationof a BoardScanner(continued)

NùcleùsUseds Guide

n-23

EXTENDED iRMXO II MULTIBUS€

print_map:

II SYSTEMS

PROCEDURE(sys_map_ptr)PUBLIC;

DECI-ARE

//,r parús

sys_nap_ptr
DECLARE

POINTER:
Iocals

sys_nap
i
status

..___/

BASED sys_map_ptr(MAXSIiTS)

map_srruc,
BYIE,
uoRD;

/*
/*

systen map */
loca1 indèx */

CALL rqc$send$eo$response(NIL, 0 , G( 2 , odh, oah) , €scarus ) ;
CAIL rqc$send$eo$response(NIL, 0 , @( 17 , ,
SYSTEM|,fAP,,odh,oah) , @srarus ) ;
cAr,r-rqc$send$eo$response(NIL,0,G(23,,board
sloc,,Odh,Oah,Odh,Oah),
@sEarus);
\!-/
Do i = 0 ro MAXstoTs -1;
CALL rqc$sèndgeo$response(NTL,0, @sys_nap(í) . íd,Gsratus ) ;
,),esratus);
CALL rqcgsendqeo$response(NIL, 0 , @( 5 , ,
CALL out_bytè ( sye_Í,ap ( i ) . s ror_ntllì) ;
CALL rqcqsend$eo$response(NTL,0, @(2,oDH,oAh), Gstatus ) ;
END;
END princ_map;
DUCI,ARE

g|obaLs */

iPsB_slot
s ratus
count
vendor_id_1o
vendor_id_hi
id_char
local_slot
psb_reg_off
r-tyPe
sys_nap (uAxSmTS )
/*

becin

\-,

BYTE,
/*
i,ùoRD
BYTE,
,/*
BYTE,
/*
BYTE,
BYTE,
/*
BYTE,
,/*
I{ORD,
,/x
3YTE,
/*
map_struc;/*

psb slor

currenrly

scanned *,/

index tnro id srring x/
lorn'byte of vendor id */
char:acxer in board id */
slot mrnrber of 1oca1 hosr */
offset
of psb control
record */
record. type returned by ffnd_record
map of boards ín syscen */

main */

CALL set$exception(NoEXCEPT);
DO lPSB_s1ot : 0 To MAXSLOTS- 1;
sys_map ( iPsB_slot) . slot_num : iPSB_s1ot;
vendor_id_lo = rq$get$ interconnect ( ipSB s1or, VENDORIDREG.
@status);
CALL error$check( 130, status);
Figure 12-6. Implementation

t2-24

ofa Board Scl|nnet (continued)

NucleusUset's Guide

EXTENDDD
iRMP ITMULTIBUS@
n sYsTEMs

* Only check status after first
* co seè íf call is confígured
* by geE$interconnecÈ)

call to get$ lnterconnect,
(no other error is rèturned

- rq$get$ tncerconnecr ( ipsB_s1or,
vendor_id_hi
CALL error$check( 140, sratus);
* If vendor_id is not equal to 0, then there
*òoard in this s1ot, so get the boaÌd,s ld

VENDORIDREG+I,Gscacus);
ís a

IF ( (vendor_id_hi
0R vèndor_id_lo)
o 0) THEN DO;
count : o;
sys_nap ( i!SB_s1ot) . fd ( 0) : BoARDIDLEN;
DO I{4iILE (count < BoARDIDLEN);
id_char - rq9get$ interconnect ( iPSB_s1ot, BoARDIDREC+counc, @status)
CALL error$check ( 150 , status);
IF (id_char <- ,!,) oR (id_char >- ,t,) rHEN
id_char = , ,;
sys_map ( iPSB_s 1ot) . id( counr+1) - ld_char;
count=count+I;
DND;
END;
ELSE

,),
CALL novb(@(10,,EMpî|l
Gsys_nap( tpsB_e1ot ) . td, BoARDTDLEN+1);
END;
/*
* Nor' get slot
uber and id of local hosr.
To access loca1 irìcercon* nect, the special slot nullber, I,oCALHoST, nust be used
r_cype = fÍnd_record(IiCALI{OST,pSBCoNTROLREC,Gpsb_reg_off)
II r_type o RECNoTF0UND
THEN Do;
= rqsget$ inrerconnecr (I.OCALHOST,psb_reloff
local_s1or

;
+ pSBSLOTIDoFP,

@status);
CALLerrorgcheck( 160, status);
loca1_slot = shÌ(1oca1_s1ot,3);
sys_nap(1oca1_slot). slot_nun = Iocal_slor:
count - o;
D0 ilrItILE (count < BOARDIDLEN);
id_char - rqqget$interconnecr(IoCALHOS1, BOARDIDREC+couot,
@srarus) ;
CALI-error$check( 170, srarus);
lF (íd_char <= ,!,) OR ( id_char >- ,),) THEN

id_char = ' ';
sys_nap(local_slor).' d(count+l) = id_char;
count=counÈ+1;
END;
END;
CALL prinr_nap (@sys_nap) ;
CALL rq$exitQio$j ob (0,NIL,@srarus) ;
END ic;

Figùre 12-6. Implemenfationof a BoardScanner

Nndeu! Uset's Guide

12-25

EXIENDED iRM)@ II MULTIBUS@ II SYSTEMS

Figure 12-7. SampleScreenOutput Fmm the InterconnectExample

Figure12-7showsa sampleoutputof theboardscanner
example.
12.5.6.2Creatinga Portfor Message
Sendingand Receiving
Once you have ioformation on what boards are in your system,the next step is to create a
pofi for messagepassingand associatea buffer pool with it. The following example
creates a buffer pool, releasesa number of 1K buffers to it, and then creates a data
transport type port and returns a TOKEN to use as a reference to the port.
This module is not run from the Human Interface. it is called by the other modules
described in this chapter.

12-26

NucleusUsedsGuide

EXTENDEDiR]\fi@ II MULTIBUS@II SYSTEMS

$tlt1e('crport

- create a port end attach a buffer pool to ít,)

/*****************************************************************rl*r!***rt***
*
INTEL CORPORATION
PROPRIETARYINFORI{ATION
*
*
*
*

This sofcl{Étte is supplieal unater the tenns of Ér
llcense agreelnent or nondisclosule
agreenenc wich
lnte1 Corporation and Ìnày not be copted or dtsclosed
except in accordance wlth the terns of that €treemenc.

*
*

1987, 1988

*
*
*
*
*
*
*

For Incel customers licensed for the íRlfl{ II Operating
Systern under an Intel
Software License Agreenenc, this source code and
object code deríved therefron
are licensed for use on e single central
processlng unit for internal
use only.
Necessary backup copies and
nultípte
perlllitled.
Object Code der:iwed fron this source code
is a Class I sofu,/are product under the Intel
Sofcxrare License Agreement
and is subject to the terrÌs and conditions
of that agreenent.

*
*

Fo! the right
to nake lncorporations,
or to transfer
chlrd perÈles, contacc Intel corpofatioo.

thís

softsare

/***:l****rt*it***it*)t)t*rt*************************it*****:t**rt*******:t***********/
crPofc:

D0;

tlncrude
I include
$include
$include

( / rrú.yz ò 6/ l ncl rnxp rn . exr)
(/Ìnx28 6/1nclerror.
1it)
(dcon.1it)
(err. ext)

DECI.\RE
NOEXCEPT LITERATLY

'0'i

no exception

handling

by system */

Figure 12-8. Creatinga Dataîlaùsport ProtocolPort (continued)

Nùcleus Ilsefs Gùide

t2-27

EXTENDED iRI{X@ II MULTIBUSo

leJ ec.
$ subtitle

II SYSTEMS

( ' create$bufqpool ' )
**************.***************Jr*****

PRoC NAMETcrèategbufgpool

* DESCRIPîION:

Creare a buffer
a11er.
Create
release thero to
the buffer pool

*
*

* CALL: bufgpoolgtok

pool \rirh rhe acrribures
passed by che
an 1n1r1a1 number of 1K buffers
and
the buffer pool.
Return a coken for
to the caller.

= creategbufgpool

(nax_bufs , inir_nurD_bufs,
ttrs,
status_Ptf)
nax_bufs - naximtrll nxnber of buffers
for buffer pool
inít_num_1,ufs - ínitial
nuDber of buffèrs
for buffer
Pool,
- buffer pool creairion atrributes
attrs
- poínts to a status word
status_ptr

* INPUîS:
*
*
*
x

* RETURNS: bufspoolgtok

- token for

newly created

buffer

;

\.--l

pool

*********:t**************)t*********rt******************************>t*>t*/

create$buf$pool:
PUBLIC;

(nax_bufs , i ír_num_bufs, arrrs,
PROCEDURE

max_bufs
init_nw_bufs
attrs
status_ptr

status
buf_pool
buf_tok
i
DECLARE
BUFSIZE
BI'LAGS

TOKEN

/* Paraneters */

DECIARE

DECI,ARE

stacus_ptr)

WORD,
lrORD,
llORD,
PoINTER:

/*
/*
/*
,/*

maxirnunrnunber of buffers
in buffer pool */
tnitial
number of buffers
in pool */
*/
buffer pool creation
atttibutes
*/
exceptlon póinter

/* Local Variables *'/
BASEDsrarus_ptr

/* Líxerals

WORD,
îOREN, /* buffèr pool conplere with buffers
ToKEN, /* buffeÌ token */
UoRD; /* local index */

LITERAI-LY '1024' ,
IITERAI,LY '0108,;

/* b!îfer sj-ze */
,/* single buffet, don,r release *,/

buf_poo1 : rq$create$buffer$pool (nax_bufs, attrs,
CAIL errorqcheck( 10, stacus);

status_ptr);

Figtlre l2-8. Creating a Data Transport Protocol Port (contirued)

72-28

NucleusUsedscuide

*,/v

EXIENDDD iRMX@II MULTIBUS@Il SYSTEMS

DO i : 1 to init_nutÌ_bufs;
buf_tok = lqgcreate$ segnent( BUFS
IZE, statrs_ptr);
CALLerror$check(20, status) ;
CALL rqqreleasegbuffer (buf_poo1 , buf_rok, BFtAcS, srarus_prr);
CAIL error$check(30, status) ;
END;
RETURN
buf_poo1;
ENDcreate$buf$poo1 ;
$eject
$subttcle ( ' ret$dporÈ' )
/********************rt*:t********************>t**************r!*********

PROCNAI4E: gèt$dport
DESCRIPTION:Thls procedufe creates a pott for data transport servlce.
A buffer pool is created and attached to the port.
A token for the newly crèated porÈ and buffer pool are
rètuhed to the cal1er.
If eíther port or buffer
creaÈion fai1s,
che call returns rrrlrh neither
e buffer.
pool or port created.
CAIL: dport$cok

: ger$dporr (porr_nun, buf_pool_prr,
sratus_Ptr)

b_aftrs,

port_nur0 - port nunber asslgned to neÌ,r1y created port
- buffer pool creation
b_attls
arÈiibutes
scatus_ptr - polnts ro sracus word
- points to buffer pool token attached to
OUTPUTS: buf_pool_ptr
the newly created port
RETURNS: dporr$tok - Èoken to newly created port
INPUTS:

******x******)t****:r:t:r**:t*:t***x*:r*!r***************rr**************x****/

get$dport:

(port_nun, bufu)oo1_ptr ,b_arcrs , starus_?cr)
PRoCEDURE

DECI,ARE

port_nun
buf_p óo1_p tr
b_attrs
stacus_Ptr

Paraúeters

ToKENpuBl-tc;

WORD,
POINTER,
INORD,
POINTER;

porc id for nelr port x/
points
buffer

Èo buffer
pool */
pool creation
actríbutes

Figurel2-8. Crcatinga DataTEnsportProtocolPort (continued)

NucleusUsefs Guide

12-29

EXTENDED iRTD(@II MIJLTIBUSO T SYSTBMS

DECLARE

/* Lltèrals

NUU_TRANS LITERALLY
DATACOM LITERALLY
PFLAGS
LITERALLY
MAXBUFS LITERALLY
INITBUFS
LITEMIIY
DECIARE

\_,.
'10',
'2'
,
'0'
,
'30',
'10';

/*
/*
/*
/*
/*

na-y nurlber outstandtng trens €t port */
indícates data con port */
fifo, fragrnentation flags */
naxínun il buffers tn pool */
initial
nunber of buffèrs */

Locals */

bpool BASEDbuf_pool_pcr ToKEN,
TOKEN,
Port_t
bufpool_c
TOKEN,
port_info
porc_ínfo_s,
loc_status
WORD,
status BASEDstatus_Prr woRD;
/* BeCin tet$dpott

/x local por].- */
/* buîîex pool with inieial
buffers */

alloc

/* local stacus nord */

-_-/

port_info . port_id = port_nun;
port_lnfo. type - DATACoM;
porE tnfo. rrags - vlr-Acs;
port_t : rq$create$port (NUM_TRANS
, €port_lnfo, stàtus_ptÌ);
CALLerror9check(40, status) ;
bufpool_t - creategbuf$pool(IIAXBUFS, INIîBUrS, b_attrs, status_pÈr) ;
CALLerror$check(50, status) ;
bpool - bufpool_t;
CALL rqqattach9buffer$pool(bufpool_t,
port_t, status_pÈr) ;
CALLerror$check(60, status) ;
porr_t;
RETURN
ENDget$dport;
ENDcrport;
\_,-/
Figùre U-8. Creating a Data Transport Prutocol Port

12-30

NucleusUset's Guide

EtrIENDED iRMX@II MULTIBUS@Il SYSTEMS

12.5,6.3SendingDataUsingRQ$SEND$RSVP
Now that you haveinformationon the boardsin the systemand a dataport you are ready
to senddatain messageform. The nextexampleillustratesone of the mostcornmon
passingformats,the request/responsgtypicallyusedbetweentwo Extended
message
iRMX tr hosts. Tlvo termsusedîo describethe boardsinvolvedin request/response
messages,
are 9!949whichindicatesthe requestingboard andsele! whichindicatesthe
respondingboard.
Figùre l2-9 showsthe logicalrepreseotationof the message-passing
modelfor a
request/rerponsetransaction.A taskon the clientboard initiatesthe hansactionby
sendingan RQ$SEND$RSVP
call to a well-knom port ofl the seryerboard. Becausethe
portson a remoteboardcannotbe dynamically
determined,
thisexampleassumes
a port
that is createdon all boardsasa startingpoint for message
passing.Onceyou havea
HOST$ID for a remoteboardyou combineit with the PORT$ID of this ,'well-known"
po.t to createthe socketfor the destinationof a message.Whenthe serverboard
receivesthe messageit replieswith the RQ$SEND$REPLYcall. The request/response
messages
continueuntil the datarequestedin th€ original RO$SEND$RSVPsystemcall
is receivedby the task on the client board.
For this examplewe are assumingthe following:
.

the port on the client boardhasa singlebuffer largeenoùghfor the reqùesteddata

the port receivingthe RSVPmessage
is not beingùsedasa sirlk port

Figure 12-10is ari algorithmfor this transactionandFigùre 12-4Ehowsthe physical
locationof the boardsin a sysrem.

NucleusUset'sGuide

t23l

EXTE\DED iRVX@II MTJLTTBUS€
U SYSTEMS

B O A R DI S S U I N G
T H E F S V PC A L L
C L I E N TB O A R D
B U SI N T E R F A C E

RECEIVE

LocaC
l PU

BOARD
R E P L Y I NTGO T H ER S V PC A
SE R V E RB O A R
D
8 U SI N T E R F A C E
RECEIVE

L o c a lC P U

fIn
SEND

SEND

- -n

Operationsthat are transpaaèntto calling tasks
LEGEND

lll€sseg€Pasling Bus

1 . Th6taskonths Cli€ntboardissuesan RQ$SEND$RSVP
call. In an RSVP/R
EPLYfansaction.th€
boardthatissuesth6s6ndRSVPisth€cli€nt;theboardthatr€pli€sis the;erver.
2. TheNucl6usCommunication
Servic€tumsthe
inlormation
in th€'RSVP'system
callintoa messag€,
and ssls up th€ bufferspacefor th6 sxp€ctedreply.
3. Th€ MPCsendsth6 messagoacrossa m€€sagepassingbusto the remoteagerìrspecifed in rho BSVP
syst€mcall.
4. TheCPUon th€s€N€rboardr€coives
a PICinterupiinforming
itthata MULTTBUS
llm6ssagehas
5. TheNucleusCommunication
port
S€tuiceonihe seNerboad dirgctsth€message
to the appropriat€
{andther€for€task.)
Task2 respondswith an RO$SEND$REPLY
systemcallthat corìtainsinformationaboutthe data being
safi,
7. Th6NucleusCommunication
Seruic€
on ths s6N€aboardturnsth€information
in tha
RQ$SEND$REPLY
callintoa message
thatis sentbytheMPC.
8. fh€ m€s6age
travolsacrossths msssagepassingbus,an operation
thatis transpar€nt
to th€ op€Éting
systemson both boards.
9. Th€ ÀlPCon th€ clierìtboard placesthe messag€intoths buff€rthat was set up in slep two, and thsn
sendsan ìnterrupt
to th6 CPU,informing
it of thecompletion
of the m€ssage
transaction,
10. TheNucleusCommunication
S€rviceon th6clieÍt boarddirectsthe messag€
to th€cor€cttask
usìnglhsPORÍ$|0.TheCPuon ths cli€ntboardis 'aware'of ontyth€op€rations
performed
in steps
1,2,9,and10.

Figure 12-9.An RSVP/REPLYTransactionbetryeerT\yoExtendediRMlp II Hosts

12-32

NucleùsUset's Guide

EMENDED IRMX@II MULTIBUS@II SYSTEMS

Client board
CalI an external procedure called get$dport thar returns a TOKEN
for the 1oca1 porr ro be used in rhe RegSEND$RSVP
caII.
Initlalize
the socket structure,
declared externally.
sec the nessate slze co be zero length.
Equate che global variable
rs\rp_size to che LITEML RSVPB (128 bytes.)
lssue the RSVP systen call ustng rhe prevtously ínirialized
variables.
Use the Rq$RECEM$REPLY sysrem call ro wait for an ans\.'er.
Send thé reply nessage, "This is a send$reply,,message" to the console screen.
Exlt froro the éxamD1e.

Ftgùe 12-10. Algorithrh for RQ$SENDSRSYPExampte

Ca1l an excernal procedure, get$dport,
that relurns a TO(EN to
be used in thè RQ$RECEIVEand RQgSENDgREpLy
calls.
PelforÍì an RQ$RECEM using rhe TORENrerurned frorn ger$dporc
Perforo an RqSSEND$REPLY
on successful conpletion
of the RQ9RECEM
IF the daca ar.riwes correcÈ1y. nsg_pcr I
NIL
Retuh che buffer
ro rhe buffer pool
End server procedure

Ftgùre l2-ll AlgorithtÍ for Server Board

This examplemustbe run with the folloli,ingexampleshownin Figure 12-13.To run
theserwo examples,first on the hostin slot five qrpe:
RC!'I,ISG

Then on the host in slot onetype:
SNDRSV?

NucleusUsels Guide

t2-33

EXTENDED iRMX@II MULTIBUSO II SYSTEMS

$titÌè('sndtsvp

- initiaté

e request-rèsponse

transaction'

)

/***5t******)l$t******:l*****************************************************)t*

INTEL CORPORATION
PRO?RIETARYINFOR}IATION

*
'l
*

This softuare is supplied under the terns of a
ttcense agreenent or nondísclosure atreeoenl vlth
InLel Corporation and may not be copied or disclosec
excepl 1n accordance wich the terns of that agteenent.

*
*

Intel coriporation 1987, 1988
rielÌÈs reserwed

*
*
*
*
*
*
*

For Intel cuscomers licensed for the iRl{x II operatíng
Systen under an lntel
Sofbrare Lícense Agreement, thls source code and
object code derived therefron ar:e licensed fol use on a single cenEral
processing unlt for lnternal use on1y. Necessary backup copies and
multiple users are pernitted.
object Code derived flon this soulce code
is a Class I sofùrare prodùct under. ttl€ Tntel Software Licènsè Agreenent
and is subjecc to the teLns and conditions
of that agreement.

*
't

Ior the right
to nake incorporations,
ot to Cransfer
thlld parCíes, contact lntel corporation.

this

software

/:l*:l*****rt*********************rt******************:f************************/

.-/

/********rt*:l*********************************************************
*

MODULENAME: sndls,"?

*
rt
*

DESCRIPTION: Send a transaction
request to a lre1l-known socket.
The request
is sent as an unsoliciCed nessage, ie wich no dara parÈ. ttait
for a response and print
the nessage o Lhe consoLe.
\-/

**:t************:t*:t***************:t*************)t*:t********rt********:t*/
sndrsvp: DO;
$include
Sínclude
$include
$ incrude
$incÌude

(/rmx286/inc/rn ,
con_buf (CoNBUF)BYTE,
rs'vT_buf (RSVPB)BYTE,
ness_size
DWORD,
rsq_slze
DWORD,
rsw_prr
PoINTER,
lnfo
rec_info,
buf_pool
ToKEN,
trans_id
WORD;

,/*
/*
/*
/*
/*
,/*
/*
/*
/*
,/*
/d

Token for local porx */
socket ro which nessage is senr *
dlioró alias for messock */
control b\tffer */
rsvP buffei */
nurnber of byres in dara úessaae *
rsw buffer size */
poinrs ro rsw message*/
receive info block */
buffer pool aÈrached ro porr */
rransacbior id ,r/

CALL setgexception(NoÉXCEPT);
port_t = get$dporr (TSTPORT
, @buf_poo1,CHAIN,@starus);
nessock. host_id - REtfHoSTtD
;
nessock.port_ld = REMPORT;
mess_size - 0;
rsw_size = RSVPB;
trans_ld - .q$send$rsvp(porÈ_r,nsock, Gcon_buf, NIL,
ness_size, @rsw_buf, rsw_size, SFl,AcS,@status);
CALLerror$check( 100, status);
rslT_ptr : rq$receive$reply (port_c, rrans_id, I{AITFOREVER,
Gínfo, Gsrarus);
CAI-I.errorgchéck( 110, starus);
call rqc$send$eo$response
(NIl,0 , Qrsq_buf, @sracus) ;
CALLerrorgcheck(120, sratus):
call rq$exir$io$job(0,NIL,Gsracus) ;
ènd sndrsvp;

Fig].úe12-12.Client BoardCodefor Re$SEND$RSVpExarnple

NucleusUset's Guide

f2-35

EX-ITNDEDiRMX@II MULTIBUS@fl SYSTEMS

$title('rcvrsvp
9conpacÈ

- respond to a request-response

transactiont)

\.__,/

/****rl***rt******)t*:l***tr*****************************************************
*'
INTEL CORPORATION
PROPRIETARYTNFORMATTON
*
*
*
*

This software ís supplied under the terins of a
Iicense €Breenent or nondisclosure aEreement víth
Tnteì Corporation and nay not be copied or disclosed
excepc in accordance lrith the terns of that agreement.

:f
'I

Intel corporation
ritlrEs resefved

1987, 1988

à"
*
*
*
*
*
*

For I$tel
cuslroners licensed for the iRl,lx 11 Operating
System under an Intel
Softlrare License Agreenent, thts source code and
ot'ject code deríved therefron are licersed for use on a single central
processing unic for incernal use only.
Necessary backup copies antl
multiple users are pernitted.
Object Code derived fron thís source code
ís a Class I softnare product under the Intel. SofÈsaÌe License Agreenent
and is subjecc to the terms and condítíons
of that agreenent.

*
*

For the fight
to nake Íncorporations,
or to lransfer
third parties,
contact Intel corporation.

this

software

\_-/

/*********:t*:t************************)t*************************************/
/****************)t*********************)t**:r**************************
*

MODUIENAME: rcvrsvp

'l
*

DESCRIPTIoN:Ilhen a ness-ge is received,
and exiE.

*:f*********:l**************)t***)t*)t************:t*:!************it****rt***

rcvfsw

send a response via rq$send$reply

i DO;

$include
9include
9include
$ include
9ínclude

(/rnx2B6/ínc/rnxp1m.
ext)
(dcon. èxt)
(dcon.1it)
(/rmx28 6/inclerror
. 1it )
(err. exi)

Figure 12-13. llre Server Board Code to Receive and Answer an RSVP Message (Corìtiùqed)

12.36

NucleusUsels cuide

,,,t

E)NENDED iRMX@II MUI]TIBUS@N SYSTEMS

DECI,ARE
TSTPORT
SFLAGS
NoEXCEPT

DECI-ARE
status
port_t
ínfo
buf_póo1
nes_buf(*)
Èran_ld
con_buf (20)
r0sg_ptr

LTTEMLLY
LîîERALIY
LITEMLI-Y

Llterals

clobal

woRD,
ToKEN,
rec_info,
ÌoKEN,
BlaE iniÈial
l{oRD,
BYTE,
POINTER;

'801H"
'000008',
'0'i

/*
/*
/*

\rel1-known porr */
daxa b!îfer,
synchronous flags*/
no exception handlíng by system */

vars */

/*
/*
/*

/*
/*

Token for loca1 port */
info block on nessage received */
buffer pool attached to port */
(30,.Thts ís a scnd$rep1y méssege. ,Odh,oah),
control
polnter

nessage buffer */
to received nessage */

CALL set9exception(NoEXCEPT);
port_t - get$dport (îSTPORT, Gbuf_poo1, CHAIN, @srarus);
msg_pcr - tq$rece íve (por.È_t, I,IAITFoREVER,Gínfo, Gsratus);
C A L L e r r o r $ c h è c k( 1 0 0 , s t a t u s )
cran_id = rq$send$reply (po{r_c, info . rengsocker,
info. transgid, @con_buf,
faines_buf, SIZE(nes_buf ), SFI,\GS, @status) :
C A L L e r r o r $ c h e c k (1 I 0 , s t a t u s ) ;
II nsg_ptr o NII- THEN D0;
CALL rq$release$buffer (buf_pool , seleccorgof(nsg_prr),
(info.flags
Gstatus);
cALr èrror$check ( 100 , status);
END;
6ALL rq$exít$io$j ob(0,NIL,Gstatus) ;
END rcvrsvp;
FiguÌe 12-13. The Server Board Code to Receiye and Answer an RSVP Message

12.5.6.4Sendinga DataChainMessage
This sectioopÍesentsan exampleof sendingandreceivinga messagethat is in datachain
form. The exampleis presentedfurtwo modules,onethat sendsthe datachainand one
that leceivesit. Note that a port's ability to receivemessages
in daîachainform is set
accordingto the attdbutesof the port's associated
bulfer pool.
This examplemustbe run with the followingexampleshownin Figure 12-15.To run
theseexampletwo commandsmustbe typed,one on eachhostterminal. Fi6t, on the
hostin slot five, type:

NucleusUset's Gulde

1237

AND 3),

EXTENDED |ITMX@I I MULTIBUS@ Ir SYSTEMS

RCVI'ÍSG

\-- -/

Second,on the host i.. rlot one,q/pe:
DCSNDMSG

The host terminal in slot five wilJ display:
This is a data chain message sent by server.

'
$ title ( dcsndnsg - send a data chaln nessage to a knol,'n port')
$compact
/:l*:!*:k****************************

*
*
*
*
*
;
:
*
*
*
*
*
*
*

INTEL CORPORATION
PROPRIETARYINFORMATION
This softvare
is suppÌied under the terns of a
t icense agreement or nondisclosure agreemen! wilh
Tntel Corporatíon and may noL be copied or disclosed
except in accordance lrith the cemts of that agreeúent.
aopyright Intet cotporation
O11 ríghts reserved

1987, 1988
\

For Intel
custoners licensed for the iRlfi Il Operating
Systen undèr an Intel
Soft\dare License Agreenent, this soù.ce code and
object code derived therefrom are lícensed for use on a síng1e centlal
processing unít for internal
use only.
Necessary backup copíes and
nultiple
pernitted.
objecÈ Code derived fron this source code
ís a Class I software product under the Intel Softlrare l-icense Agreenent
and is subject to the terms and condítions
of that agreeroenc.

*FoftherighttoÌnakeincofporations,ortotIansferthissoftwareto
*
third parties,
contact lntel corporarlon.

**********************************rf*rf*:t*Jl***************)t*:t******)t$l***:l**/

Figure 12-14.Data Chain Serd (continued)

12-t8

NucleusUset'sGuide

EXTENDEDiRMX@II MI]LTIBUS@N SYSTEMS

/*******:t************)t***:l*****rt*****)t****************)t**************

MoDULENAME:dcsndrosg

DESCRIPTIoN:
Send a data chain message.

:t***********************x************************x*xx****xx**rt*******/
dcsndmsg:Do;
$include (/rnx286llnclrnxplm.
$ include (dcom.lit)
$lnclude (/rnx28 6/inclerror.

exc)
lir)

$iDcÌude (err. exL)
DECIARE

I-irefals

LITERALLY 'STRUCTURE(/* data chain elernent *,/
b_size
ÍJoRD,
/* b\tfer size */
buf_ptr
P0INTER, /* buffer poínrer */
les
lioRl)',
/* reserved */
REMPORT
LITERAI-LY ,801H',
,/* porc id of re ote porr */
REMHOST
LITERALLY '05',
/* Host id of remote host */
'16'
CONBUF
LITERALLY
*/
,
/x slze of a control buffer
TSTPORT
LITERALT,Y '801H"
*/
/* r,el1-known pofr
'46'
MSIZE
LITERALTY
,
/* rf.èÉèage eize *//
'I00',
BUFSIZE
LITERALLY
síze j./
/* b!îfer
'0',
NOEXCEPT LITERALLY
/* no excepÈion handling by systen */
t8'i
DCBUFSIZE LITEMILY
,/* data chaiD buffer size *,/
dc_el

DECIAE

G1oba1 vars */

stacus
itORD,
port_t
TOKEN,
nessock
sockèt,
nsock
DI]ORDAT (@nessock),
con_buf (CONBUF)BYTE,
ness_size
l,loRD,
bpool
TOKEN,
offset
WORD,
/*
sflags
WoRD,
dc_seg_size I,IORD,
dc_seg_t
ToKEN,
poINTER,
dc_ptr
d_cheín based dc_ptr(1)
dc_el,
dc_idx
I,IoRD,
trans_id
I,ORD;

,/* Token for 1ocal porc 'kl
/* socket to which nessage is sent */
/* d\i'ord alías for nessock */
/* control buffer */
/* nurnber of bytès in data message */
,/* buffer pool arcached to porx */
buffer offset !ùhere chain buffer srarrs
/* Cransnission flags */
/* segUent size for daca chain */
/* token for data chain segnent */
/* poi cer Lo daÈa chain segÌnenc */
/* data c}.ain */
/* dara chain index */
/* transacLion id */

Figue 12"14.Data Chain Send(continued)

Nucleus Userts Guide

12-39

EXIENDED iRMX@tr MULTIBUSo fi SVSTEMS

DTCL.AÎE
dc_buf (BUFSIZE) BYTE INITIAL
(45,'Thís is a data chain nessage sent by server ' , odh, oah) ;
CALL setqexceptíon(NoEXCEPT);
port_t = get9dport (TSTPORT,Gbpool, CttAIN, @status);
nìessock.host_id - REMHOST;
- REMPoRT
nessock.port_ld
;
/*

eteaxe data chain with
buffer + a terninating

at least
block */

enough blocks

for

each message

ness_size - SIZE(dc_buf) ;
*
*
*
*
*

calculace the slze of the segnent that rri1l concain the data chaln.
The message is divided lnto pieces lrhose size is DCBUFSIZE so the totel
nunber of elements in the daia chain is ness-size/DCBUFSIZE + 2.
The additional 2 includes one possible piece of the nessage less than
DCBUFSIZEand the terninating
data chain elenent.

':-/

dc_seg_size - (ness_size/DCBUFSIZE+ 2 )* (size (d_chain) ) ;
d^_seg_t - rqScre€te$sègment(dc_seg_size. @status) ;
dc_ptr - build$ptr ( dc_seg_t , 0) ;
/*

Fill
ín the fields
of the data blocks
a part of che message */

for

each buffer

offset : 0;
dc_idx - 0;
DO latlTLEoffset < ness_size;
d_chain(dc_idx).b_size - DCBUFSIzE:
d _ c h a i n ( d c _ i d x ) . b u l _ p t r - G d c _ b u (f o t r s e t ) i
offser = offsec + DCBUFSIZE;
dc_idx:dc_idx+1;
END;
n.h,in/,1.
iàw\ h t*rt********:!***********
X
INTEL CORPORATION
PROPRÎETARY]NFOR!{ATTON
*
*
*
*

Thls software is supplied under the terns of a
llcense agreenent of nondisclosure
agreenent with
lnte1 Corporation and nay not be copied or dlsclosed
èxcept tn accordancè wlrh rhe rerÌs of thar sgreenenc.

copyríghr Inrel corporation
O1l righcs reserved

1987, 1988

;
*
*
x
*
*
*
*

For Intel customers licensed for the iRIflt II Operarint
System under an Intel
Sofb/are License Agreement, this source code and
object code derived therefroo are licensed for use oo a single central
processíîg
unit for internal
use on1y. Necessary backup copies and
rDultiple users ere pernitced.
Object Code deÍived fron this sourcè code
is a 01ass I sofLware producr under rhe tnrel
Sofúrare Llcense Agreemenr
and is subject to the terms and conditions
of chat agreement.

*
*

For the right
to nake lncorporations,
or to transfer
third pertles,
contact Intel corporation.

this

sofbrare

/********************5t**************!r*rr************************************/
/********************:l**************r!*******************)t***:t****rt***
*

MODULE N t{Er

DESCRIPTION: llhen a nessage is received,
determine
whether
it is ln data
hain or buffer
forn.
If data chain,
compress the chain into
a single
segnenc.
Expect a 2K nessage with a printable
part at the firsc
and second 1K + 2 boundaries.
tfrice
rhe
printable
part to the console.

*
*
x

dcrcvmst

**!t***)!**************>t*:t*:t*********:t**:t$t****************************/
dcrc1,Ìlsg:

DO;

$include (/rnx286/lnc/rroxp1m. ext)
$include (dcon. exc)

$include (dcoro.lit)
9include (/ri[x286linclerror
9include (err. exc)

, 1ít)

Figure 12-15. Receivea Messagein DataChain Form (continued)

NucleusUset'sGuide

t2-41

EXTENDED iRMX@ II MULTIBUSO II SYSTEMS

.:
DECI,ARE
îSîPORT
NoEXCEPT
DECIARE

Llterals

'801H',
tot
i

IITDR.ÀILY
LITERATLY
G1oba1 vars

\?
/* ve1l-kno.lln port */
/* no exception handlint

by systen

:*/

status
IIORD,
TOKEN'
Port-t
1oca1_hos!
IioRD,
tnfo
rec_lnfo,
bPool
ToKEN,
dcmsg_ptr
P0INTER,
lrsg_ptr
PoINTER,
nsg BASED dcDsg_ptr (1) BYTE;

/*
/*
/*
/*
/*
/*

Token for 1oca1 Port */
1oca1 host id */
lnfo block on Dessage tecelved */
buffer Pool */
poÍnter to data chaín message */
pointer
to received message */

'get$dc$data'
$:ublí ll e(
)
/******rt*:t******:t*****)t*****************************t<****************

\-/

PROCNAì{E| get$dc9data

*
*
rt
*

DESCRIPTION: Thfs procedure takes a daca chairì and copies the daca described
by it lnto a siogle segllent.
this procedure only works if the
data ís less than 64K ln size.
Data chaíns can describe data
grearer rhan 64K.

CALL: nbuf_ptr

*
*

T\PrnS.

:!
*

RETURNS:nbuf_ptr

- get$dc$data(dc

prr,

\--

status_ptr)

d. ntr - nniFrs Lo a data chaín
- polnts co a status word
scatus_ptr
- polnts to a segment containíng
descrlbed by a data chajn

the data

***************************************************,t*****************//

get$dcqdata: PRoCEDURE(dc_ptr,status_ptr)

PoINTERPUBLIC;
\*7

DECIaRE

dc_ptr
status_ptf
DECI,ARE

Parans */

PoINTER. /* points
PoINTÈR: /* polnts
/*

L/Jcals

Lo data chain *,/
to status wofd */

Figue 12-15.Receivea Messagein Data Chain Form (continued)

12-42

NucleusUset's Guide

EXTENDEDiRj\,fr@ II MULTIBUS@II SYSTDMS

dc BASEDdc_ptr (1)
status BASEDstatus_pcr
num_bytes
cpybuf_tok
cpybuf_ptr:
cpybuf BASEDcpybuf_ptr
I
cpyidx

blk_struc,
WORD,
IIORD,
/*
TOKEN, ,/*
POINTER,/*
c_buf,
WORD, /*
ITORD; ,/*

nu.nber of bytes in dets chaln */
buffer to hold data chain data *,/
points to cpyb\tf */
1oca1 index */
iDdex into cpybuf'*/

nun_bytes - 0;
i : 0;
/* get the size of the data described by the data chaín */
DOlttILE dc(i).b_size c

nun_bytes - nun_bytes + dc(i).b_size;
END;
/* add 2 to

nun_byles

for

the

síze

field

c_buf

nun_bytes - nun_bytes + 2:
cpybuf_cok = rq$creste$segnent (nun_bytes , statusjtr);
CALL error$check ( 100 , sraLus):
cpybuf_prr - òulld$prr(cpybuf_cok,
0) ;
- nun_bytes - 2;
cpybuf.slze
i = 0;
cpyídx - 0;
DO iarHILEdc(í).b_size
o 0;
CALL novb(dc (i) .buf_ptr, ecpybuf ,buf (cpyidx),
cpyidx - cpyid.! + dc(i).b_size;
I - i + 1 .
END;

dc( i) .b_size) ;

RXrLEN cpybuf_ptt;
END get$dc$data;

Staxx

Î.aír, */

CALL set$exception(NoEXCEPT) ;
port_t = get$dport ( TSTPoRT,Gbpool, CHAIN, @status);
= rq$receive (port_t,
mslpcr
WAITF0REVER,@info, @status);
CALL error$check(110, scaLus) ;
IF (info.ftags
Al{D DATACHAIN)= DATACHAINTHEN Do;
dcnsg_pcr = get9dc$data(nsg_ptr,
@status) ;
CALL error$check( 120 , status);

Figue 12-15.Receivea Messagein Data ChainForm (continued)

NùcleùsUsels Gùide

12.43

EXTENDED iRMX6) II MULTIBUSo

:t print nessage that xras contained aÈ start
* hw rhè fírsr clpmFnr ín the data chain

II SYSTEMS

of Èhe buffer

( 2 ) , @status ) ;
CALI- rqc$send$eoqresponse (NIL, 0 , @msg
CALI- error$check ( 130 , status);
* prlnt nessage that was contalned ac start
* by the second elenent ln the data chaln

of the buffer

( 1026 ) , @status ) ;
CALL rqc$send$eo$response (NIL, 0 , @rnsg
CALL error$check( 140, status);
END;
EI,SE DO;
caLL rqc$send$eo$response(NIL,0, msgl,tr, @status ) ;
CALL error$check( 150 , status);
END:
cAlL rq$release$buffer (bpoo1 , SELECToR$oF(nsg_pcr),(info.flags
@status);
CALL rqSexít$io$j ob(0,NIL,@stacus) ;
END dcÌca'nsg;

described

\.-_7
AND 3),

Figure 12-15.Receivea Messagein Data ChainForm

12.5.6.5Sendinga Messagein Fragmenis
This sectionpresentsan exampleof serdingandreceivinga message
that is broke[ into
Iragments.The exampleis presentedin two modules,one thaî seddsthe fragmented
messageand ofle that receivesit. Note that a port's ability to receivemessages
rn
ftagmentform is setaccordingto the attribìÌtesgivcnto the port at the time of its
creation.
This examplemustbe run vr'iththe RSVPprocedureshownin Figure 12-12.To run this
exampletwo commandsmustbe typed,one on eachhostterminal. First, on the hostin
slot five, type:
SNDFRAC

This procedurewill breakthe datainto îragmentsartdsendthemto the processorboard
in slot one.
Second,
on thehostin slotone,qpe:
SNDRSVP

This procedurewill receivethe fragmenteddataand displayin on the termioa,.
Thehostterminalin slotonewill display,"This is a reply sent in fragDents."

t2-44

Nucleùs UserJsGuide

._/

EXTENDEDiRMX@II MULTIBUS@tr SYSTEMS

- send e fragnented Dessage,)

$tille(rsndfrag

/**********************'t******:t*:t*:t**********:!*:!*:!*à!********:t*:!*:r***********

INTEL COR?ORATION
IROPRIEÎARY INFORMATION
*
*
*
*

This soffirare is supplied undet the terl[s of a
license agteenent or nondisclosure
agreement rrlth
lntel
Corporarion and nay noc be copied or disclosed
except in accordance with the tenos of tbat agreenent.

Copyrighr Intel
Corporeri.on
O11 righrs resened

1987, 1988

;
*
*
*
*
*
:t
*

For Intel customers lícensed for the iRl0a lI Operating
System under an Intel
Software ticènsè Agreemenr, rhis source code and
object code derived rherefron
are ltcensed for use on a single central
processing unlt for internal
use on1y. Necessary backup copies and
nultlple
users are pernitted.
Object Code derived fton thís source code
is a Class I softùare product undet che Ince1 Software License Agleenent
and is subject Èo the terns end condtrions
of thar atreenenc.

*
*

For the right
to make incorporatlons,
or to transfe!
third parties,
contact Intel corporation.

this

soffidate

//******************)t**:t***********rt*rt**********rt*rt*****************:t*:t*****//
/*****************x*x*:r****xrvx*****rt****xxx*x************************
UoDùLE NAME: sndfrag
DESCRIPTIoN: Receive a transaction
nessage.

request,

send che reply

ss a fragÌented

********************************!r****+*************
sndfrag:
$íùclltde
$includè
$include
$ ínclude
$include

DO;
nes_size THEND0;
ftag_slze : úes_slze - roes_idx;
sflags - EOTFI,ACS
,
END;
tran_id - rq$ send$rep1y
(porr_r, info. rengsocker, ínfo.rransgid,

9:îi.l"t;-9:.:-P:r(nes
r! róÉr r rc5LéLus/,
CALLerror$check(110, status);
nes_tdx : nes_idx + FRAGLEN;
END;
lF msg_ptr c NIL THEND0,
CALLrq$releese$buffer(bufjoo1,
CALI-errorgcheck( 110, status);

1dx), rras size,

selector$of (nsg_pcr), 0, @sratus);

END;

END;
CALLyq$exit$io$l oh(0,NTL,Gstàtus);
ENDsndfrag;

Figue 12-16.Senda Messagein FragÌents

'12.5.6.6
Receiving
a Messagein Fragment
Form
This sectionprcsentsan exampleof sendinga message
and receivingit in fragmentform.
The exampleis presentedin t,ro modules,one,SFRAG, rhat initiates a transactiorwhich
forcesreceivingto be donein fragmentform. The other module,RCVFRAG which
receivesthe messageandprints it on the consolescreen.To run this exampletwo
commandsmustbe tped:
First, on the hostin slot five, type:
RCVERAG

Second,on the host in slot ore, t'?e:
SFRAG
The host terminal in Slot one will display:
Thís is a reply Èo a fragnented nessage.
The host terminal ir Slot five will display:
îhis

ts the second fregnent.

NucleusUset'sGuide

12"47

EXIENDED iRMI@ II MIJLTIBUS@ II SYSTEMS

$titlè('rcvfreg

- receÍvè e fragnentèal ruessegè'
)

SconDact:

*************x***********
/*********************************
*
INTEL CORPORAT]ON
PROPR]ETARY
INFORMATION
*

Itris

*
*
*

license egreenent or nondlsclosurè
agrèenent wlth
IÍtel
Corporalrion ard nay not be copled or dlsclosed
except ín accordance ldíth the Èerns of that agreenent,

software is supplied wúer

*
tr

the tenDs of a

1987, 1988

*
*
*
*
'l
*
*

For Intel custonels licensed for the iRlDt II operattng
Systen uùder an lnte1 Softwale Llcense Agreeùent, this source code and
object code derlved therefrorn are licensed for use on é single cenlral
processirg
unit for internal
use on1y. Necessary backup copies aaal
nultiple
users are pemltced.
object Code deríved flon this source code
is a Class 1 softlrare product undel the Intel Softùare License Agreenent
and is strbject to the terms and conditions
of that agreenent,

x
*

For the rlght
to make incorporations,
or to transfer
third parties, contact Intel corporation.

this

softvrare

_,,,

Èo

\-,

/:*************************5!***********************************rf************/
/****************************************************!t********)t*)t**rt*

* MODULENAìIE: rcvfrag
* DESCRIPTIoN: Receive a fragmented nessage and princ
at the beginning of each fragment.

the message contained

Îhe task leceives a printable
nessage.
lf chere is not enough
buffer
space to recelve the entíre nessage, receive the message .-'
(The info data structure
in fragrnents.
associated with the
rq$recèíve call contains the nìessage length and lhe Cransaction
ld necessary co recelve che message in fragnenrs.)
Princ
the nessage and send a printable
nessage co the sender.
*************>t***************************************r!*:t*************/

(continùed)
Figure12.17.Receive
in Fragments
a Message

12-48

Nucleus
Uset'sGuide

EXTENDEDiRMX@II MULTIBUS@Iì SYSTEMS

rcvfrag: DO;
$include (/rnx286/ínc/rmxp1m. ext)
qin.lt!?ìó,/7i^^ó

Àwr\

ìrncruoe(ocon. rl El
$ include (/rnx286/1nc/error
ain.l,..rè,/érr

DECI,ARE
FRACLEN
BUFFRAG
TSTPORT
sFl-AGS
NOEXCEPî

DECURE

. 1ít )

--'\

Lítèrals

LITEMILY
LIaERALLY
LITEMLLY
LITERALLY
LITERAI-LY

CIobaI vafs

'1024'
,
'O'
,
' 801H'
,
'000008',
'0';

/*
/*
/*
/*
/*

fragmentacion buffer
length */
fragnenc ls buffer flag x/
r'el1-knoran por:t */
data búffer, slnchronous flags*/
no exceptlon handling by syscem */

status
porc_t
info
buf_pool
rùes_buf(*)

WoRD,
TOKEN.
,/*
rec_info,
/*
TOREN,
/*
B\IE initial

tran_id
bytes_rec
con_buf (20)
frag_buf(FRAGLEN)
nsg_ptr

WORD,
/*
WORD,
/*
ByIE,
/*
BYTE,
/*
PoINTER; /*

Token for local port */
info block on nessage received */
buffer pool attached t:o por:x */
(41,'ftis
is a reply Èo a fra8 enced
nessage',odh,oah),
transaction
id */
number of bytes received in ness fragrnents */
contÍol nessagè buffèr */
fragnentation
buffer: */
pointer to received message */

CALL set$exception(NoEXCEPT);
port_t - get$dport ( TSTPoRT,Qbuf_pool, NoCHAIN, Gstatus);
nsg_ptr = rq$receive (port_t , WAITFoREVER,
@info, Gstatus);
CALL errorgchèck ( 100 , 5Èatus);
IF info.sÈatus:
E$oK THEND0; /* nessaBe may not be fragnented */
CALL rqc$ send$eo$response(NIL, 0 , nsg_ptr , @status ) ;
CALL error$check ( 120 , srarus);
tran_id - rq$ send$reply (porr_r , info.rem$socke!,
ínfo. trans$id, Gcon_buf,
\ o m e s _ b u, f s i z e ( n e s _ b u f ) . S F I A C S .@ s t a r u s r ;

(continued)
Figure12-17.Receive
a Message
in Fragments

NùcleusUsePscuide

12-49

EXTENDED iRMI@ II MIJLTIBUS@ II SYSTEMS

CALLexror$check(130, status);
IF msg-ptr o NIL THEND0,
CAI-Lrq$release$buffèr (buf-pool , sElEcîoR$oF(nse-ptr), (iÎ1fo.flags AND3),
Gstatus) ;
CALLerror$check( 140, status);
END;
END;
ELSEDO;
1î ínfo. status = E$NOSLoCAL$BUFFER
THENDo;
,/* receive ÎragnenLs and print ÍÌessageat beginning of fra&nents */
bYces-r:ec= 0;
D0 i{ùILE bytes_rec < info.daEa$Ienglh;
carl' rq$receíwe$frasnent(port_t, info. rèm$socket, info. trans$íd,
Gfrag_buf, FMGLEN, BUFFRAC,@status) ;
CALLerror$check( 150, status);
byces_rec : bytes_rec + FRAGLEN;
CALL rqc$sendqeo$response(NIL,0, Gfrag_buf, estatus ) ;
cALr error9check(160, status);
END;
,/* complete transaction by sendlng a printable message*/
f ^(---r
/RtM286/DEMO/ì:-[L/MB2INSER!R
This commandmakesthe directorycontainingthe nameseNerexamplethe current
directory. Next,qpe:
SUBMITCOMP]LE

This commandinvokesa CommandSequence
Definition (CSD) file that generatesthe
executablenamesetverand all of its aequiredmodules.
Ihe nameservercanbe run asa backgroundjob oneof the processors.To sîdrt the name
serverrunningasa backg.oundjob gpe:
BACKEROUND
NSERVR
> NSERIR.DOC

Seeflre Extended|RMXII OperqtorhGuídeTo TheHumanInterfacet.narl]ual
îor
informaîion on the backgroundcommand.
Two modulesare providedwhichdemonstratethe useof tbe nameserver. NSSNDMSG
andNSRCVMSGwhichexecuteasa pair. NSRCVMSGmustqecute fist, it postsa
socketwith the nameserverunderthe name"receiver.',NSSNDMSGthen executes,
sendingthe tameservera look-uprequeston the name'receiver.i NSSNDMSGthen
sendsa messageto rrreceiver";
NSRCVMSGprints the message"Thisis a simple
messagerr,
to the temínal console.
This processcanbe demorstratedon eiîher hostboard,but the order of moduleexecution
cannotbe chansed,

NucleusUset's Guide

t2-55

E)|TENIIED

iRMX@ II MI]LTIBUSO

II SYSTEMS

12.6 GLOSSARY
AgCa!-Any board that is connectedto the MULTIBUS II parallelsystembus(iPSB).
businterface-TheMessage
Passing
Coprocessor
(MPC)chipis sometimes
referredto as
the businterface. The purposeof the MPC is to providea transparentinterfacebetween
thelocalCPUandtheparallelsystem
bus(iPSB).
Q[9O!-A physicalboard (usuallya processorboard)that requestsa servicefrom another
board.Duringa readfrom a disk,theprocessor
boardthatrequests
thereadis theclient.
SeealsoServer.
clatachain-A methodof receivingdatamessages
that arelargerthananyonebuffercan
hold. Datachainingis performedtransparently
by the systemhardware.
d4.!4g!4q-Themessageformat usedby MULTIBUS II. Datagramscanbe descdbedas
similarto mailinga letter. Youwritea letter,address
it, put a stampon it a placeit in a
mailbox.You assume
thattheletterwill getto its destination,
or if a replyis needed,
you
put an RSVPh theletteritsel|
Interconnect
S''ace--Agroupof 512registers
thatcontaininformationabouteachboard.
primary
jumpers.Theconfiguration
The
useof thisspaceis to replacephysical
of a board
canbe changedby writing to interconnectspacerather than insertingor removingphysical
jumpers.
4gggggg-Alldataandinterruptssentoverthe MULTIBIIS TTParalelSystemBus(iPSB).
Messages
canbe thoughtofas a blockof bytessentoverthebusthatcontainsall ofthe
informationneededto sendthe message
to theintendeddestination
agent(board)and
receivea reply,if requested.Two t)?es of messages
are supportedin MULTIBUS ,
solicitedandùnsolicited.Seealsoùnsolicited
messages
andsolicitedmessages.
pe4-A datastructuredefinedin thetransportprotocolthatis usedin passing
messages.
It providesa levelof addressing
permits
thar
sending
datato a particularîask(program)
runningon a board.
$gryg-A physicalboard (frequentlya cont.ollerthat providesdatastorage)that provides
a seNiceto anotherboard.Duringa r€adfrom a disk,the controlleîboardthat doesthe
readandsendsthedatato the requestor
is the serve-r.
SeealsoClient.
soli(ìtedmessages--Any
datamessage
thatrequiresnegotiatioÍfor bufferresources.
Solicitedmessages
areusedto senddata,suchasdiskreadandwritedata,from one
boardto another.(Seealso,message
andunsollcited
message.)

12-56

NucleusUset's Guide

EXTENDED
iRMX@II MULTIBUS@
[ SYSTEMS

source/destinationaddress--Aneight-bitfield in everymessage
passedon the paraÌlel
systenbus(iPSB). This eight-bitfield alows the unsolicitedmessageto act asa virtual
interrupt, this addressingschemepermitsa total of 255possibleinterlupts or board$,in a
singlesystem.
unsolicitedmersages--Any
messagethat come$overthe iPSBbusthat wasnot requested
by the receivingagent(board). Unsolicitedmessages
are usedasinteÍùpîs, or mntrol
signals,Theyrelievethe local CPU from havingto poll for messages
comingover the bus.
The unsolicitedmessageis 32 byteslong. (Seealso,message,
solicitedmessagqand
sou.ce/destinationaddress.)
virtual interrupt*A software-routedinterrupt that is containedin a MLILTIBUS II
message.EachMULIBUS II message
containsao eight-bitfield that specifiesthe
sourceanddestinationof the message.Thesesouce and destinationbits allow the
messageto act asat interrupt to the MessagePassingCoprocessor(MPC).

NqcleusUset'sGuide

l2-57

13.I INTRODUCTION
The Nucleusis a configurablepart of the operatingsystem,It containsseveraropuons
that you canadjustto meetyour specificneeds.To helpyou makeconfigurationchoices,
Intelprovidesthreekindsofirformation:
. A list ofconfiguîableoptioos
.

Detailedinformation aboùtthe options

Proceduresto helpyoù speciryyoùr choices

The rest of this chapterprovidesthe first categoryof information. To obtain the second
and thiÌd categoriesof information,refer to theìRlvD{II IntemctiveCotufrgumtion
Utilíty
RekrcnceManual.

13.2 HARDWARE
The operatingsystemsupportsa varietyof hatdwareenvftonments.By usingthe ICU,
you cantailor the operatingsystemto matchyour hardware.In particular,you canspecily
informationaboutthe followinghardwareelements:
Timer

You canspecirythe timer'sbaseport, intervalbetweenports,clock
interrupt level,andclockfrequency.

NPX

You canspecifuthe additionof a NumericProcessorExtensionfor tasks
requùingfloatingpoint insîructions.The defaultoption assùmesthat no
NPX is present,If there is an NPX in youl system,bùt you do not indicate
it duringconfiguration,your applicationcamot useNPX instructions.If
you speciryan NPX duringconfigurationandyour systemdoesnot contaú
an NP)q you maycauseunexpectedresults.

NucleusUsedsGuide

13-1

NT]CI,NUSCONI'IGfIRATION

13.3 SYSTEMCHARACTERISTICS
Whenyou configlre the Nucleus,you canspecirya numberof chaÌactedsticsthat affect
yoursystem:
Parameter
Validation

A systeúcallvalidatesinput parametersby checkingfor the
existenceof objectsandby verifing that the objectsare the correct
t pe. If your systemdoesnot includethe BasicI/O Slstem,you
carlexcludeparametervalidationfrom your system.

GDT Entdes

EachiRMX II objectrequi.esonecDT eùtry. Therefore,you
needto configurethe ùumberof GDT slotsyour systemrequtes.

IDT Entries

You canallocatethe numberof IDT entdes,up to 256,that your
systemneedsin the interrupt descriptortable.

Default Exception

You cafl choosefrom oneof four optionsfor your systemdefault

Handler

handler:

RoundRobin
Scheduling

Usethe systemdefaultexception
handlerthat deletesoffending
tasks.

Use the alternativesystemexceptionhandlerthat sùspends
mtherthandeletes.

Use the iRMX II SystemDebuggerasthe exceptionhandler.

Supplyyour ownexcepîioohandler.

\'_ -'l

\__/

You candetermineif round robin schedulingwill be in effeat. lf
so,you cansetthe priority belowwhichtaskswill be assigned
round robin scheduling,and the numberof clockticks eachtask
mayrun beforebeingrescheduled.

NucleusUsertsGuide

NUCLEUSCONI'IGIJRATION

13.4 SYSTEMINITIALIZATION
ERRORREPORTING
During the configurationprocess,you canelectto haveinitializstion errorsreportedfor
eachlayer of the operatingsystem.This is doneby coofiguringInitializarion Error
Reporting(RIE) into your systemv/henyou configùrethe Nùdeus. Then,wheneverthe
operatidgsystemencountersan initialization error in a layer,it displaysthe following
messageand relinquishescontrol to the monitor:
Initialization

Error:

lf Initialzation Error Reportiry is oot configuredinto the Nucleusand an initialization
error occurs,a codeindicatingthe layer respoísiblefor the initialization effor andthe
corespondiùgerîor codeare placedin the first two wordsof the Nucleusdata segment
(1E0:0000H).The NÌrcleusinitialization taskthen goesinto aù in{irfte loop.
The codesfor the laye6 that cancausean initialization error are
1 = Nucleusfailure
2 - BIOS failure
4 = HumanInterfacefailure

NucleusUsey'scuide

13-3

The ExtendediRMX II OperatingSystemrecogúzesthesedatat pe.s:
BYTE

An unsigned,eight-bit,binarynumber.

WORD

An unsigned,two-blte, binarynumber.

DWORD

An unsign€d,32-bitbinarynumber,occupyingtwo cootiguous
wordsol memory.

INTEGER

A signed,two-byte,binarynumbersto.edin two'scomplement
form.

POINTER

Two wordscontaioingthe segÍieùtselectorand an offset,(offset
first).

SELECTOR

A 16-bitquantitythat is equivaleotto the selectorportion of a
POINTER.

TOKEN

A word containilg îhe logicaladdressof an object. Tokensare
selectorsthat referencean €ntry ift a descriptortable, The entryin
the descriptortablecorÌtainsth€ physicaladdressof the object.

STRING

A seque[ceof consecutivebyteshavilg this structure:
length BYTE,
chars (255) BYTE;
The filst b)'te contaiDsthe length of the string (the number of
succeedingb,'tes).
The subscript of the chars field (255) is the maximum number of
bytes in arly string Note, that some systemcalls limit strhgs to
lengths shorter than 255 bytes.

NucleusUset'sGuide

a-l

8.1 INTRODUCTION
This appendixiists the typecodesfor all iRMX II objects. In addition,it documentsthe
amountof memoryneededto createBasicI/O Systemobjects.

8.2 OBJECTryPES
Each iRMX 1I objectt}?e is knownwithin iRMX lI systemsby meansof a numericcode.
Table B-1 lists the types with their codes.

TableB-1. Type Codes
OBJECTTYPE

NUI\iIERIC
CODE
1

Task

Maìlbox

Sehaphore
Region

S€gment

Extension

7
I
l CrO

Connection

101

l/O Job

300

LogicalDevice

301

User-Created
Composhe
NOTE:

vari€sfrom 8000Hro
oFFFFHdependingon lhe value
speciried
in C8ÉATE$EXTENSION

L'sersandconnectionÈ
aredesctibed
intheE tendedLRMXII Btltíc I /O 9stem
User\ Guídz in Volume 2 l/O iobsandioqicaldevicès
erc deicribèdiî,thaExÍended
|RMX II btekded I/O StstemReÍercnceManual

NùcleusUset's Guide

B-1

iRMX@II OBJECTTYPESAND RESOURCEREQUIRXMENTS

8.3 RESOURCE
REOUIREMENTS
The BasicI/O Systemobtainsmemoryfrom the callingjob's memorypool whencreating
obje.cts.The valueslistedhere refleci Release3 of the iRMX II OperatingSystem.

8.2

Object

Numberof 16-b1teparagraphs
requiredby the BasicI/O Syst€m

I/O Result
Segment

4 (5 for an intemal IORS that the Operating
Systeúcreateswheoattachinga device)

Connection(to
namedîile)

Connectíon(to
physicalfile)

User object

3 (mínimum)

NucleusUset's Guide

C.1 INTRODUCTION
TableC-1providesa c.mplete list of the ExtendediRMX II condirioncodesrhat can
occul duringsystemoperations.It lists the conditioncodesby layer with their numeric
valuesalld mnemonics.
TableC-1. Conditionsard Their Codes
Category/
Mnemonic
E$OK

E$TlME

E$MEM
E$BUSY
E$LIMIT

E$CONTEXT

E$E)CST

NucleusUset's Guide

Meaning

Numeric Code
Hex
Decimal

The mostrecenîsystemcall was
successful.

NucleusEnvironmentalConditions
A time limit (possiblya limit of
zerotime) expiredwithout a task's
requestbeingsatisfied.

Thereis not sufficientmemoryavailableto satisrya task'srequest.

Anofher taskcurrentlyhasaccessto
the datap.otectedby a region.

A taskartemptedan operationwhich,
if it hadbeensuccessful,
wouldhave
violateda Nucleus-enforced
limit.

A systemcall wasissuedout of
co[text or the operatingsystemwas
askedto perform an impossible
operation.

)t1

A toke[ pammeterhasa valuewhich
is not the token of an existing
oolect.
--continued

c-l

EXCEPTIONCODES

TableC-1. ConditionsAnd Their Codeslcontinued)
Category/
Mnemonic

Meaning

Numericcode
Hex
Decimal

A taskattemptedan operationwhich
wouldhavecausedan impossible
tîansitionof a task'sstate.

E$NOT$CONFIGURED

This systemcall is not part of the
presentmnfiguration.

E$INTERRUPT$SATURATION

An interrupt taskhasaccumulatedthe
maximumaÌlowablenumberol SIGNAL$INTERRUPT reqùests.

E$INTERRUPî$OV.
ERFLOW

An intenupt taskhasaccumulated
more than the maximumallowable
amountof SIGNAI-$INTERRUPI requests. OAH

E$TRANSMISSION

A NACK,tìmeout,or buserroroccurred

OBH

E$SLOT

Thereare no availableGDT slots.

0cH

E$DATA$CI]AIN

A datachainhasbeenreturned.The
tokenpointsto a datachainblock.

ODH

E$STATE

NucleusCommunications
SystemEnvironmentalConditions
E$CANCELLED

A SEND$RS\rytransactionhasbeen
remotelycancelled.

0081H

225

E$HOST$ID

Thehost$idportionofthe socket
parameter
is not valid.

00E2H

226

E$NO$LOCAIT$BUFFER

The localbuffer is too smallto
holdthemessage
data.

00E3H

227

E$NO$REMOTE$.Thebufferon theremoteagentis
BUFFER
too smallto holdthemessage
data.

00F'tH

228

E$RESOURCE$- Either the simultaneousmessages,
o!
LIMIT
or trarisactions
is not adequate.
--continùed-

00E6H

230

c-2

NucleusUserrsGuide

EXCEPTION
CODES

TableC-1. Corditions And Theh Codeslcontinuedì

Category/
Mnemonic
E$TRANS$ID

NumericCode
Hex
Decimal

Meaning
The transmissionis alreadydone,or
the specifiedtrans$idis invalid.

OOESH

E$DISCONNECTED

The socketis zero andthe localport

OOEgH

E$TRANS$LIMIT

Therehasbeena transmission
resourcelimitation.

OOEAH

232

234

I/O SystemEnvironmentalConditions
E$FEXIST

The specifiedfile alreadyexists.

20H

E$FNEXIST

The specificdfile doesnot exist.

2r}l

E$DEVFD

The devicedriver andfile driver
are not compatible.

22H

Thecombination
of parameters
enteredis not supported.

23H

The speciliedentryin a directory
file is empty.

The specifieddirectoryentryindex
is beyondthe endof the directory
file.

25H

The connection
doesnot havethe
correctaccessto the file.

26H

The requestedoperationis not valid
for this file type.

The requestedoperationattemptedan
improperkind of file sharing.

28If

E$SPACE

There is no spaceleft on thevolume,

29Il

E$IDDR

An invalid devicedriver request
occùrred.

2AH

An I/O error oc.curred.

2BIf

E$SUPPORT
E$EMPTY$E$DIR$END

E$FACCESS
E$F:TTPE
E$SHARE

E$IO

-continued--

Nucleus flse s Guide

c.3

EXCEPTION CODES

TableC.1. ConditionsAnd Their Codes(continued)

Category
I

Mnemonìc

E$FLUSHING

Themnnectionspecified
in thecall
wasdeletedbeforethe operation
completed.

2CH

The devicecontainsan invalidor
improperlyformattedvolùme.

2Dtt

E$DEV$OFFLINE

The devicebeingaccessed
is now
offline.

2EH

E$IFDR

An invalidfile driver request
occurred.

2FH

E$FRAGMENTATION

The file is îoo fragmentedto be
extended.

30H

E$DIR$NOT$.
EMPTY

The call is atte.nptingto deletea
directorythatis not empty.

31H

E$NOT$FILE$CONN

parameter
Theconnection
is a device
connection,not a file connection.

32Ij

E$NOT$DEV.
ICE$CONN

Theconnection
parameter
is not a
deviceconlection.

33H

) I

E$coN'l.I$NoT$OPEN

The connectionis not openfor
readingwritingor updating.

34H

E$CONN$OPEN Thetaskattempted
to opena
connection
thatis alreadyopen.

35H

E$BUFFERED$- The specifiedconnectionwasopened
CONN
by theEIOS,andusedby theBIOS
which is not allowed. Onceyou have
youmust
an openconnectlon,
manipulateit with a systemcall
providedby the sameI/O S1,stem.

36H

E$ILLVOL

E$OUTSTAND.
ING$CONNS

c.4

A soft detachwasspecified,but
connectioDs
to the devicestill
exist.

NucleusUset's Guide

EXCEPTIONCODES

TableC-1. ConditionsAnd Theh Codeslcontinued)

E$ALREADY$ATTACHED

The specifieddeviceis already
attached.

38H

E$DEV$DETACHING

The file specifiedis on a device
that the operatingsystemis in
the processof detaching.

39H

3AH

The call is attemptingto renamea
directoryto a newpathcontaining
itself.

3BH

A strcamfiÌe requestis out oi
context. Either it is a query
requestandanotherqueryrequest
is alreadyqueued,or it is a
satis8'rcquestand either the
reques.queueN empryor a query
requestis queued.

3CH

The connectionrefersto a file with
an invalid fnode. You shoulddclete
this file.

3DH

E$PATHNAME$.
SYNTAX

The specifiedpathnamecontains
invaÌidcharacters.

3EH

E$FNODE$LIMIT

Thevolumeaheadycontainsthe
maximumnumberoffiles- No more
fnodesare availablefor newfiles.

3FH

40H

E$NOT$SAME$- The existingpathnameandthe new
DEVICE
pathnamerefer to different devices.
You cannotsimultaneouslyrenamea
file andmoveit to anotherdevice.
E$ILLOGICAIJ.
RENAME

E$STREAM$SPECIAL

E$INVALID$.
FNODE

E$LOG$NAME$. The specifiedpathnamestaÍs with a
SYNIAX
colon(:), but it doesnot containa
second,matchingcolon;the specified
pathname
hasmorethan12characters
or containsinvalidcharacters.
E$IOMEM

Nucleus Uset's Guide

The BasicI/O Systemhasinsufficient memoryto proccssa request.

c-5

EXCEPTION CODES

TableC-1. ConditionsAndTheirCodeslcontinuedì

E$MEDIA

The device containing a specified
file is not on-line.

E$LOG$NAME$- The specified path contains an
NEXIST
explicit logical name, but the
Extended I/O Systemwas unable to
lind the namein the object
directoriesof the localjob, the
globaljob, and the rootjob.

45H

E$NOT$OWNER The userwho attemptedto detachthe
device is not the owner of the
device.

E$IO$JOB

46H

'70

41H

i. rhè.;ohr f^r-"r

48H

The usernamespecifiedin the call
is not listedin îhe Ilser DeJ:nition
File.

49H

't3

The userID in the specifieduser
objectdoesnot matchtheID listed
in the User Definitior File for the
corresponding
username.

4AH

The Efended I/O Systemcarinot
createan l/O job becausethe size
specifiedfor the objectdirectory

E$UDF$FORMAT The User Delinition File is not
E$NAME$.
NEXIST
E$UID$NEXIST

E$PASSWORD.
$MISMATCH

E$UDF$IO

The passwordspecifiedin the call
doesnot matchtheoneIistedin the
User Dcfinition File for the corrcspondingusername.
'I'he
User Definition File specified
cannotbefound.

48H

4CH

o@ufred.

50H

A soft I/O error occurred.A retry
might be successful.

51H

E$ro$uNct-assAn unknowntypeof I/O
E$IO$SOFT

c-6

error

NudeusUset'sGuide

EXCEPTION
CODES

TableC.l, ConditionsAnd Their Codeslcontinued)

Category/
Mnemonic

Meaning

NurnericCode
Hex
Decimal

A hard l/O error occuÍed. A retry
is probablyuseless.

52H

The devicewasoff-line. Operator
interventionis required.

53H

E$IO$WRPROT

The volumeis ìryrite-protected.

54H

E$IO$NO$DATA

A tapedrive attemptedto readthe
nex1iecord, but it foundno data.

55H

A tapedrive attempteda read/write
operationbeforethe previouswdte
(read)completed.

5óH

An attemptwasmadeto assignan
altemateback, but no Ílore altemate
trackswere available.

57I{

An alternatetrack wasassignedduring
thisI/O operation.

58H

headerrecord.

62Il

The ApplicationLoaderencountered
an uneripected
end-of-filewhile
readinga record.

65H

101

Thereis insufficientmemoryto
satisrythe memoryrequirements
of the ApplicationLoader.

67H

103

The ApplicationI-oadercouldriot
find the start addre.ss.

6CH

108

6DH

109

E$IO$IIARD
E$IO$OPRINT

E$IO$MODE

E$IO$NO$.
SPARES
E$ro$Ar-T$ASSIGNED

ApplicationLoaderEnvùonmentalConditions

E$BAD$HEADER The objectfile containsan invalid
E$EOF

E$NO$LOAD.
ER$MEM
E$NO$START

E$JOB$SIZE

Nucleus Useas Guide

The maximummemory-poolsizeof the
job beingloadedis smallerthan the
amoult of memoryrequiredto load its
objectfile.
.continued

c-7

EXCEPTION CODES

TableC-1, CondltlonsAnd Theh Codes(continuedl

Caregoryl
Mnemonic

Meaning

NumericCode
Hex
Decimal

The overlaynamedoesnot matchany
of the overlaymodulenames.

6EH

110

The lile requiresf€aturesIrot
supportedby the ApplicationLoader
asconfigured.

6FH

111

The parsingbuffer containsa
literal with no closingquote.

80H

128

The stringto be retúrnedexceeds
the sizeof the buffer the user
providedin the call.

81H

129

The parsingbuffer containsa
comúandsepafator,

82H

130

Tho paÉebuffer containsa
continuation
character.

83H

131

E$INVAL]D$.
NUMERIC

A numericvaluecontainsinvalid
characters.

84H

132

E$LIST

A valuein the valuelist is missing.

85H

E$WILDCARD

A wild-cardcharacterappearsin an
invalidcontext,suchasin an intermediatecomponent
of a pathname.
the commandline mntainsan invalid
preposition.

86H

134

87H

135

88H

136

E$OVERI.AY
E$LOADER$.
SUPPORT

Human Interface Envhonme[tal Conditions

E$LITERAIE$STRING$.
BUFFER
E$SEPARATOR
E$CONTINUED

E$PREPOSI.
TION
E$PATI]

The commandlLre contaiosan invalid
pathname.

E$CONTROI"$C The usertyp€da CONTROLC to abort
the command.
E$CONTROL

c-8

The commandline containsan invalid
contrcL
--confinued

89H
8AH

138

NucleusUset'sGuide

EXCEPIION CODES

TableC.1. ConditionsAnd ThetuCodeslcontinued)

Category/
MlIemonic

NumericCode
Hex
Decimal

Meaning

E$UNMATCHED-The numberof files in the input and
$LisTs
output pathnamelists is not the
same.

8BH

139

E$INVALID$DATE

The operatorenteredan invalid date.

8CIt

140

E$NO$PARAMETERS

A commandexpertedparameterqbut
the operatordidn't sùpplyany.

8DH

1.41.

E$VERSION

The HumanInterfaceis not compatible
with the versionof the commandthe
operatorinvoked.

8EH

142

A commandcalledC$GET$OUTPUT$.
PATIINAME before calling
C$GET$INPUfiPATTTNAME.

8FH

143

90H

L44

91H

145

E$GET$PATH$ORDER

E$PERMISSION l'he userdoesnot havepermissionto
to access
therequested
resource.
E$]NVALID$TIME

The operatorentercdan invalid time.

UDI EnvironmentalConditions
E$UNKNOWN.
$EXIT

The programexitednormally.

0cOH

792

E$WARNING$EXIT

The programissuedwarningmessages.

0c1H

193

E$ERROR$E)flT The prognm detectedeffors.

0c2H

194

E$FATAT"$EXIT

A fatal error occr.rrred
in the program.

0c3H

195

E$ABORT$EXIT

The operatingsystemabortedthe
pfogram,

0c4H

196

E$UDI$INIERNAI-

A UDI internal error occurred.

0c5H

197

--confinued

NucleusUset's Guide

c-9

EXCEFTION CODES

TableC-I. C.onditionsAnd Their Codes(continued)

Category/
Mnemonic

NumericCode
Hex
Decimal

Meaning
NucleusProglammerErro$

E$ZERO$DT!'IDE

A taskattempteda dividein which
the quotientwaslargerthan 16biîs.

8000H

3n68

E$OvERFLOW An overllowinterrupt occurred.

8001H

3n69

A tokenrelerred to an existing
objectthat is not of the required
qpe.

8002H

32770

A parameterthatis neithera token
nor an offset hasan invalidvalue.

8004H

32772

An OS extensiorireceivedan invalid
functioncode.

8005H

3n73

A$PARAM
E$BAD$CAIL
E$ARRAY$BOUND

Hardwareor softwarehasdeteatedao
affay overflow.

8006H

3n74

E$NDP$ERROR

A NumericProcessor(NPX) error has
occurred. OS extensions
canreturn
the statusof the NPX to the
exceptionhandler.

8007H

32775

E$ILLEGAI]$OPCODE

The processortded to executean
invalid instruction.

8008H

3n16

E$EMUI-ATOR$.
TRAP

An ESCinstructionwasencounteaed
vr'iththe emulatorbit setin the
machilrestatusword.

8009H

32777

A PASCALtaskhasexceeded
thebounds
of a CASE statement.

8OOAH

32778

NDP$SEGMENT- The NPX tried to accessan addrcss
that is out of segmeùtboundarie.s.
$OVERRUN

80OBH

32'179

E$PROTECTION

A generalprotectionerror.

SOODH

3n8r

E$NOT$PRESENT

A requesthasbeenmadeto loada
a segmentregisterwhosesegment
is not present.
---continued----

8OOEH

E$CHECK$EX.
CEPTION

c-10

Nudeus Uset'sGuide

EXCEPTIONCODES

Ttble C-1. Conditions and Their Codes (corlinuedl

Categoryf
Mnemonic

E$BAD$ADDR

NumericCode
Hex
Decimal

Meaning

The logicaladdressis illegaleither the selectordoesnot point
îo a valid segmeotor the offsetis
not within the sesmelt boundaries.

SOOFH

32783

E$PROTOCOL

NucleusCommunications
ProqammerErrors
The port specifiedis of the signal
80E0H
type,not the datacommunicaîion
tJpe,

32992

E$PORT$ID$.
USED

The specifiedport$id is alreadyin
use.

80E1H

32993

8082H

32994

E$NUC$BAD$BL'F The buffer referredto is invalid,or
not largeenough.
I/O SystemProgrsmmer Errcrs

E$NOUSER

No defaultuseris dcfined.

8021H

32801

E$NOPREFIX

No defar.rltprefix is defined.

8022Il

32802

E$BAD$BUFF

Illegal usageof memorybuffersin
reador writerequests.

8023H

32803

E$NOT$LOG$NAME

The specifiedobjectis not a device
connectionor file connection.

8040H

32832

E$NOT$DE!'ICE

A token parameterreferredto an
existingobjectthat is not, but
should be, a device connection.

8041H

32833

A token parameterreferredto an
existing object that is not, but
should be, a file conlection.

8042H

32834

ApplicationLoaderProgrammerEÍor
The maxirnummemorypool size
specifiedfor thejob is lessthan
the mìnimumpool sizespecified.

8060H

32864

E$NOT$CON.
NECTION

E$JOB$PARAM

-continùed--

NucleusUset'sGuide

c-11

EXCEPIION CODES

TableC-1. Conditionsantl Their Codes(continued)

Category
/
Mnemonic

NumericCode
Hex
Decimal

Meaning
HumanInterfac€PlosrammerErrors

E$PARSE$TABLES

Thereis an error in the intemal
parsetables.

8080H

32896

E$JOB$TABLES

An internal Humanlnterfacetable
wasovelwritten,caùsingit to
containan invalidvalue.

8081H

32897

is invalíd.

8083H

32899

The pathnameto be returnedexceeds
255charactersin length.

8084H

32900

The commandinvokedby C$SEND$COMMAND includesa call to C$SEND$EO$RESPONSE,
but the comúandconnection doesnot p€rmitC$SEND$EO$RESPONSEcalls.
8085H

32901

B$DEFAULT$SO The defaultoutput namestririg
E$STRING
E$ERROR$.
OUTPUT

UDI ProgrammerErlors
E$RESERVE$.
PARAM

Thecallingprogramtriedto reserve
memoryfor morethan12filesor
bùffers.

80c6H

32966

80c7H

32967

E$OPEN$PARAM The calling program rcquested more
thari two buffers when opening a file.

c-12

NucleusUset'sGuide

A
accessdghts
discussionof 6-1
aliases7-1
allocatingmemory 5-3
analoryof how MULTIBUS tr systemswork 12-2
application$2-1
assigninglevelsto eachinterrupt 9-5

b
BmBUS interconnect l2-3
bufferpools 12-10
buffer pools 5-4
buffer pools,systemcallsfor
CREATE$BUFFER$POOL12.11
CREATE$BUFFER$POOL,DELETE$BL]FFER$POOL12-14
REQUEST$BUFFER12-11
REQUEST$BUFFE& RELEASE$BUFFER i2-15
Built-in Self Tests(BIST) 12-6

c
call gates 1-7
Call-gate,s
arìdOS extensioN 1-3
caseseNitivity of objectdirectorynames 6-2
childjob 2-1
comparisonof procedures,tasks,andOS extensions10-2
compositeobjeats
deleting11-3
systemcallsfor 11-2
composiîe
objects1-2

NucleusUsefs Guide

Index-l

INDEX

conditioncodes
oéÍnèd

8- l

literal file 8-1
Énges 8-1
types 8-1
conligurationof the Nucleus,seechapter121
contextswitches3-2
co[trollL€ memorypool size 5-2
deating an OS extension 1-2
creatingriewoperatingsystemobjects 11-1
D
datachainblock 12-12
datachains12-11
datatlpe, seeAppendíx.{1
declaringyour own exceptionhandler 8-2
defaulttime quotafo. round-robinscheduling3-5
definitiod of
round-robinscheduling3-4
deletedof riestedcomposites11-5
descriptor 1-6
descriptortable,s
gtobal 1-7
intenupt 1-7
local 1-7
descriptors
aliases7-2
cautionson using 7-2
changingthe addressor lengthof 7-2
creat]lig'1.2
definingmemorywith 7-2
definitionof 7-l
deletl')g 7-2
er?licit 7-1
systemcallsfor 7-2
typecodereturnedfor 7-1
dtectory, objeat 1-4
disablinginterrupts 9-6
discussionof round-robinscheduling3-5

Index-2

\ -'l

\,_,)

NùcleusUser'sGuide

INDEX

erablingintcrrupts 9-21
enteringan object'snamein the objectdirectory 6-3
examPlcs
inteúuptservicing 9-24
ringbuflermanager11-7
exceptionhandlers
inherited 8-2
invoking 8-3
exceptionhandlers 8-2
exceptionhardling
for 80286processor8-4
in-Ihe 8-4
exceptionmode 8-3
exceptionalconditions
defined8"1
EnYironmental B-1

progmmmorerrols 8-1
exchangetypes 4-1
exe4ution
statesoftasks 3-1
extension
objects1-2

F
leaturesof MULTIBUS II systems12-1
four q?es of addressspace

rlo 123

interconnect 12-3

memory12-3
message12-3
FreeSpaceManager5-1

G
gettingari object'sname 6-2
gettingan object'stype code 6-2
globalclocl! MULTIBUS li 12-5

H
handlers
exceptional 1-8
interrupt 1-8
handling spurious interrupts 9-22

Nùcleus Usels Guide

Inder-3

INDEX

I
in-serviceregister,examining9-23
Inlerconnectaddressspace 12-5
interconnectspace,callsfor
GET$INTERCONNECT 12-13
SET$INTERCONNECT 12.13
interrupt controllers 9-3
inîerrupt descriptortable 9-4
interrupt handler,using 9-11
interrupt handlersand tasks 9-9
interrupt levels 9-3
interupt lines 9-3
interrupt mechanisms9-2
interrupt servicing,usingmultiple buffers 9-16
interrupttaskpriorities9-12
interrupttask,using9-11
interrupts
systemcallsfor 9-27
inteúupts9 or 16 8-6
interrupts,handlingspÌrriousg-22
inte.rupts,limit on outstanding9-19
iSBX I/O expamioobus 12-3

J
job 2-1
job deletion 2-2
job tree 2-1

L
limit or outstandinginîerrupts 9-19

M
mailbox

discussion
of queues4-2
mechanics 4-1
queues 4-1
mailboxes
systemcalls for 4-3

Index-4

NucleusUset's Guide

INDEX

1-\

mailboxes 4.1

memory
how to allocate 5-3
returning to the system 5-3
memory allocation 1-5
memory allocation perfomance feature 5-4
memory maragement
systemcalls 5-4
memory needed to create an object, seeAppendix 81

memorypool 1-4
memorypools 5-2
messageagents,callsfor gettinginformation
GET$HOST$ID12-14
MessageFragmertation 12-13
messagesPacgcallsfor
BRO{)CAST 12-13
CANCEL 12-14
RECEII'E 12-14
RECEIVE$FRAGMENT 12.14
RECEIVE$REPLY12-14
SEND 12-13
SEND$REPLY12-13
SEND$RSVP12-13
MessageSpaceCallsthat Supportthe MIC D eelce 12-14
movementof memorybetweenjobs 5-2
MULIBUS II hardwareoverview 12-3
MULTIBUS II systems,an analoryof how rheywotk 12-2
MULTIBUS lI systemqfeatu.esol 12-1
MLILTICIiANNEL DMS I/O bus 12-3
multiple buffersand interrupt servicing9-16
N
NUC$ERROR1.8
NucleùsCommunicationService 12-8
numberof interruptspossibleon cascaded
PICs 9-3
numberof interruptspossibleon onePIC 9-3
numericcodesfoî obje.t types,seeAppendix81

o
object access 6"2
object diectories
using 6-2

Nùcleùs Useds Gùide

Index-5

INDEX

objectdire{tory 1-4
enteri.g af! object'sname 6-3
objectqùeùes
poftion 4-2
high-performance
objectgpes 1-1
objects
extensionand composite 1-6
job 1-3
mailbox 1-5
region 1-6
segrnent1-5
semaphore1-5
systemcallsto manipulate 6-3
tasks 1-2
objects1-1
OSextension
intedaceprocedures10-7
OSextensions
andcustomized
exception
codes10-14
and error procedues 10-B
entry procedures10-7
exception
handlidgin 10-11
functionprocedure10-8
hrùctionsof the interfaceprocedures10-7
includingintoyoursystem10-14
linkingtheprocedures10-14
makingobjectsimmunefrom deletion10-15
procedures
needed1-2
systemcallsfor 10-15

P
parallelsystembus(iPSB) l2-3
pararneterobjeat 2-2
job 2-l
parent
port 12-9
ports,informationpîovidedon creatioù 12-9
port,systemcallsfor
ATIACH$BUFFER$POOL12.10
ATIACH$PORT 12.10
ATTACH$PORT,DETACH$PORT 12-15
CONNECT 12-10,15
CREATE$PORT,
DELETE$PORT12-15
GET$PORT$ATTRIBUTES
12.10,15
priorityfor tasks3-1
procedures
neededin an OSextension1-2

Index-6

NucleusUserrsGuide

INSEX

R
regrons

cautionary
notes4-10
deadlockand 4-9
discussionof sharingdata 4-6
mutual exclusion4-7
systemcallsfor 4-10
regions 4-5
relationshipsbetweeninterrupt tasksandhandlers 9-15
resourcesharing 2-1
restrictionswhenassigdinginterrupt levels 9-6
returningmemoryto the system5-3
round-robin$cheduling3-4
RQ$ERROR10.8

s
segmeds5-1
semaphores4
mutual exclusion4-6
systemcallsfor 4-5
task queue 4-4
semaphores 4-4
send$message
acknowledging4-2
sedalsystembus(iSSB)12-3
servicesprovidedby the CentralServicesModule 12.4
settingup an intcrrupt handler 9-10
spuriousinterrupts,usingGET$LEVEL to detect 9-23
systemcalls
for intenùpts 9-27
tlpe manager11-18
systemcalls 1-2
systemcallsfor
tasks3-6
systemcallsfor exceptionhandle.s 8-6
systemcallsfor memorymanagement5-4
systemcallsthat manipulatethe 80286processor'sa€cess
byte 6-1
systemcallsto manipulat€jobs 2-2
systemcallsto manipulateobjerts ó-3
systeminitialization error reporting 12-3

NucleusUset's Guide

Indef-7

INDEX

.
!-i

raskartribùtes 3-6
taskexecutionstates 3-1
taskpriority3-l
taskresources3-6
taskstateîransitioo3-2
taskstates
asleep3-1
asleep-suspended
3-2
ready 3-2
running3-2
suspended
3-2
lasks3-l
threewaysto addfunctionality
in iRMX 10-1
token l-2
toolsfor interrupts 9-2
TransportProtocol 12-8
two systemcallsthat setùp the interrupt descdptortable 9-6
rypemanager
jobsduringDELETE$EXTENSION11-5
jobs duringDELETE$JOB 1-3
typicalactionsof an exceptionhandler 8-2

u
useof PL/M-286 DISABLE statementin taskswith interruptsdiabled 9-7
usingan irrtcrruplhandlcrg- | l
usingan interrupttask 9-11

\
Index-8

NùcleùsUset's Guide

intel
E X T E N D EiD
R M X@II

BASIC
I/OSYSTEM
USERG
' SU I D E

IntetCorporation
3065BowersAv€nue
SantaCtara,California
95051

Copyrgh't,rlga8, lntelCofporatron,All
RlghtsReserved

INTRODUCTION
This manualdocumentsthe BasicÌ/O System,one of the layersof the iRMX II Operating
System.The materialcontainedhereinis intendedprimarily as introductoryand
backgroundirìformationfor usingthe systemcalls. you can find detailedinformationfor
using these systemcalls in the ExtendediRùÍX Il Basic I/O Sytem Calls RefercnceManual.
Readerswho are famiiÌar with the iRMX I BasicI/O Sysremwill alsobe familiar with the
iRMX ll version. The iRMX lI OperatingSystemis hasedon rhe iRMX I Operating
System.

READERLEVEL
This manualis intendedfor programmerswho are familiar with the concepîsand
terminolos/ introduccdinthc Extend,ed,
|RùIX II NucleusUse'sGuídcand with tlre PL/M286programminglanguage.

MANUAL
ORGANIZATION
Thismanualis dividedinto eightchapters.Someofthe chapters
containintroouooryor
overviewmaterialthatyoudo not needto readifyou areaheadyfamitiarwith theiRMX
II subsystems.
Otherchapters
containreference
materialthatyouwill referto asyou
writeyourapplication
ra!k\. You canuserhischaprerro determine
whichof rheother
chapters
youneedto read.The manualorganizatìon
is asfollows:
Chapter 1

This chapterdescribesthe featuresofthe BasicI/O Sysîem.You
shouldread this chapterilyou are goingthroughthe manualfor
the first time or ifyou havehad very little previousexposuteto the
BasicI/O System.

Chapter2

This chapterexplainssomebasicterminoÌoryassociated
with the
Basicl/O System,includingthe conceptsof systemprogmmmer,
device,volume,file, and connection-You shouldread this chapter
ifyou are lookilg throughthe manuaifor the first time or ifyoù
are unfamiliarwith the Ba5icl/O Svstem

BasicI/O UsedsGuide

PREIACE

Chapter3-5

Thesechaptersdescribenamed,physical,and streamfiles and how
to usethem. You shouldread one or more ofthese chapters,
dependingon the kindsof filesyour applicationuses.The useof
remot€files is rìot describedin thìs nranual.

Chapîer6

This chapterdescribesgeneralinformationaboutsynchronousand
asynchronous
systemc.dls.

Chapter7

This chapterliststhe configurationoptionsthat pertain to the
BasicI/O System.

CONVENTIONS
This manualusesthe followingconventtons:
. 'l he term "iRMX II" refersto the ExtendediRMX IT.3OperatingSystem.
. The term 'iRMX l" refersto the iRMX I (iRMX 86) OperarjngSystem.
.

All iRMX II systemcallsbeginwith one of two standardprefixes: RQ$ or RQE$.
When referringto the systemcalÌsthat beginwith RQ$, this manualusesa shorthand
notation and omits the prefix. For example,S$CREATE$FILEmeans
RQ$S$CREATE$FILE. The actualPLlM-286 externaìorocedrrrenamesusedto
invokethesesystemcallsare shownonly in the Enended 'RMX11ErrendedI/O System
CallsRekrcnceManual,whichlists the detaìledcallingsequences.

All iRMX II systemcallsbeginwith one oftwo standardprefi\es: RQg or RQES.
When referringto the systemcallsthat beginwith RQ$, this manualusesa shorthand
notation and omits the prefìx. For example,A$CREATE$FILE means
RQ$A$CREATE$FILE. The actualPL/M-286 externalDrocedllrenîmes usedto
invoke thesesystemcallsare shownonly in the Ertended.RMX ll B&\ic I/O S)stem
CaIb Refercnce
Manual,whichlists the detailedcallingsequences.

When referringto systemcallsthat beginwirh RQES,this manualspellsout the
completenames,includjngthe RQE$ characters.

You can alsoinvoke the systemcallsftom assemblylanguage,but to do so you must
obeythe PL/M-286 callingconventionsthat are discrissed
in the Errended.iRtltx
Progmmn i ng Teclhi4ue: Manual.

BasicI/O Useis Gùide

CHAPTER
1
FEATUFES
OFTHEBASICI/O SYSTEM

PAGE

CHAPTER
2
FUNDAMENTAL
CONCEPTS

PAGE

Basicl/O Usey'sGuide

CONTENTS

CHAPTER3
NAMEDFILES

PAGE

BasicI/O Us€r'sGùide

CONTENTS

CHAPTER3 (continued)

PAGE

CHAPTER4

PAGE

CHAPTER
5
STREAMFILES

PAGE

CHAPTER6

PAGE

CHAPTER
7

PAGE

APPENDIX
A

PAGE

Basi.I/O flse/s Guide

C()NTENTS

APPENDIX
B

PAGE

APPENDIX
C

PAGE

APPENDIX
D
PAGE
EXCEPTION
CODES
D.l Overview.............
................................
D-1
D.2 Sequential
(Environmental)
Exception
Codes...........................................................
D-l
D.3 Sequential
(Programmer
Error)Exception
Codes
...................................-...............
D-2
D.4 Concurrent
(Environmental)
Exception
Codes.........................................................
D-2
D.5 Concurrent
(Programmer
Error)Exception
Code...................................................
D-3
APPENDIX
E

PAGE

APPENDIX
F
iRMX@
I AND iBMX(D
IIi BASICI/O SYSTEMDIFFERENCES

PAGE

vlll

Basicl/O Use/s Guide

CONTENTS

TABLE
B-1 T)?e Codes

PAGE
B-1

FIGURES
FIGURE

PAGE

2-l Layersof Interfacing
BetweenTasksand a Devicc...................
.................................2-3
2-2 Schematic
of Softwareat Inirialization
Time................................
...............................2-4
2-3 A Systemwith DeviceandFile Connections................................
................................2-6
3-1 Exampleofa Named-File
Tree..........._.....
...............................3-2
3-2 Computingthe AccessMaskfor a File Connection..................................................
3-10
3 3 Chronologof Frequenrly
UsedSystenCallsfor Na[retlFiles.............................3-20
6-1 SampleNamedFile Tree........................_
.................................6-5
6-2 Concurrent
Behaviorof an Asynchronous
SystemCal1..............................._........_._._
6-8

BasicI/O UseCscuide

CHAPTER
1
r/o SYSTEM

1.1 INTRODUCTION
Becausethe iRMX II OperatingSystemis designedfor useby Original Equipment
Manufacturers(OEMs), it providesa iarge numberof features-includÌngsomethat are
not generallyfound in operatingsystemsaìmedat end users.Thesefeaturesinclude
. 16M-bytememoryaddressability
.

Memory protection

Synchronousand asvnchronous
svstemcalls

Deviceindependence

Supporrfor manyLinJ"ot J<, iers

Four distinctkindsof files

File sharingand accesscontrol

Separetionof file lookup and file open operations

Control over fragmentationoffiles

Global tirne-of-dayclock

Disk integrity

Thìs chapterexplainseachof thesefeaturesand familiarizesyou wirh the terminolog' of
the BasicI/O System.

NOTt
All materialon iRMX Networking
Software(iRMX-NET)canbefoundin
the |RMX NetuorkingSoftware(/ser'.s
CuÌr1e.Thìs manualis not part of rhe
iRMX II manual
set.

BasicI/O Us€r's Cuide

l-l

T.EATURES
OF THE BASICI/O SYSTEM

1.2 16M-BYTE
MEMORYADDRESSABILITY
The iRMX II OperatiogSystemrunsin ProtectedVirtual AddressMode (PVAM) ofthe
80286or 80386processors.As a result,it can acc€ssas much as 16M byresofmemory.
The BasicI/O Systemtakesadvantageof this featureby allowingyou to createI/O jobs
with memorypoolsofup to l6M bytes. Therefore,tasksthat invokeBasicI/O System
callscan havemore codeand can havemore room for data than with ìRMX I
Applcation tasksmust uselogicaladdresses
to accessmemory. Logicaladdresses
take
the form:

selector:offset
Somedevicecontrollersalsosupporta 16M-byte
address
space.Thesecontrollers
use
physicnladdresses
(dired 24,bit addresses)
to refer to the memoryspace.lfyou l,lrire
youl own devicedriversfor theseconîrollers,your devìceclriversmust know how to
'Í\e
convertlogicaladdresses
to physicaladdresses.
Ettendedi&lvfx II DevíceDrivex
Usrr'r Gu,Zediscusses
thìs technique-

1.3 PROTECTION
FEATURES
Becausethe iRMX II OperatingSystemaccesses
the processorin pVAM, ir benefitslrom
someof the inherentmemoryproteciionfeaturesof the processor. Thcsc fcaturcs
protectyour codeand dirtaby preventingany task from readìngor writing buffersof
memory unlessit has explicitaccessto thosebrrffers.They alsopreventmemoryreadsor
writes from crossingsegmentboundaries.The OperatingSystemgeneralesexception
codesif an attemptedDrotectionviolation occurs.
The OperatingSystemalsocheckssvstemcalÌparametersfi)r protectionvìolationsand for
incorrectvalues.AppendixD liststhe exceptioncodesthat can be returned.

1.4 SYNCHRONOUS
ANDASYNCHRONOUS
OPERATION
When you examine the EÌtended ilLtvlx II Basic I/O Slstem Calb ReferenceManual,yo!
will îind that the systemcaÌlscan be dividedinto two categoriesaccordingto their names.
The first categoryconsistsof systemcallshavingnamesofthe form:
RQliXXXXX
whcrc XXXXX is a brief description ofwhat rhe sysrcmcall does. The secondcategory
consistsof systemcallshavingnamesof the fbrm:
RQ$A$XXXXX

BasicI/O Usefs cuide

FEATURES
OF THE BASTCI/O SYSTSNT

Systemcallsof the firsÌcategory,
withouttheA, aresynchronous
calls. l heyhegin
runningassoonasyourappiication
invokesthem,andcontinuerunninguntil theydetect
an erroror ac€omplish
everathìng
theyÍrust do. Îìcn theyreturncontrolto your
application.In otherwords,synchronous
callsactlike subroutines.
Systemcallsof the seconci
category(thosewith theA) arecalledasynchronous
because
theyaccomplish
theirobjectives
by usingtasksthatrun concurrently
withyourapplicrrtion.
Thisallowsyourapplication
to accomplish
someworkwhiletheBasicI/O Systemdeals
with devices
suchasdisksor tapedrives.

1.5 DEVICEINDEPENDENCE
The BasicI/O Systemprovjdcsvou with one set of sysrcmcallsthar can be usedwith any
collectionof devices.Fo. instance,rather than usinga TYPE sysiemcall for output to a
terminaland a PzuNT systemcaÌl for output to a line printer,you can usea WzuTE
systemcall for output to any device.
This notion of one set of systemcallsfor I/O to any collectionofdevicesis calleddevice
independence,
and it allowsyour applicrtionmuchflexibility. For example,supposethat
your applicationlogs eventsxs they occur. 'Ihe deviceindependenceof the BasicI/O
Systemallowsyou to createan applicalionthat can log the eventson any devicerather
lhan just one.
For instance,whenthe eventapplicationis runningand circumstanccs
forc€ an operatc'r
to reroute loggingfrom the teletypewriterto the line printer,your applicationcan be
writtento do this
For a more detailedexplanationof deviceindependence,
refer to the Introducti()nto thc
Ertendetl |RMX II Operating Sytem.

1.6 SUPPORT
FORMANYKINDSOF DEVICES
Althoughyour applicationcan be deviceindependent,the BasicI/O Systemmust be able
to communicàtewith a wide varietyof devices.To connecta particulardevìceto the
Basicl/O System,you must havea devicedriver (a collectionof softwareprocedures)
designedespeciallyfor the devicebeingconnected.
The Basic f/O Systemprovidesdevicedriversior manydevices.'fi\e EttendedíRMX II
[nteructiveConfigutatiotlUtìlityReference
Maradl liststhesedevicesand describe-r
how to
includetheir devicedriversin your appìicationsystem.Ifyou needdriversfor other
devices,you musî supplylhe drivers. F.eferto the Ertended.RMX II DevíceDivers User's
C4Ue for instructionson how to write vour own devicedriver.

IìasicI/O User's Guide

FEATURES
OF THE BASICI/O SYSTEIIÍ

1.7 FOURDISTINCT
KINDSOF FILES
Filesin the BasicI/O Systemarebyte-oriented
(asoppos€d
to record-oriented
files). The
Svstem provides you with four kinds of filcs: namcd, physical, stream, and remote.

1. 7 . 1 N a m e dF i l e s
Namedliles are intendcdlor uscwith random-access,
secondarystoragedevicessuchas
disks,diskettes,and bubblememories.They allowyour applicarionto organizeits files
into a treelike, hierarchicalstr ctnre that reflectsthe relationshjpsbetweenthe files and
the application.Furthermore,only namedfiles allowyour applicationto store more than
one file on a device,and only namedliles provideyour applicationwith ac{:ess
control.
Namedfiles alsoprovidea good startingplacefor buildingcustomaclessmethodssuchas
the indexedsequentialaccessmethod(ISAM).
For more informationregardingnamedfiles,refer to Chapter4.

1.7.2 PhysicalFiles
Physicalliles differ from namedfiles in that eachphysicalfile occupiesan entire device.
In lact, from the standpointof rhe BasicI/O Syslem,a physicalfile is a devìce. yet with
the BasicI/O System,an applicationcan dealwith a physicalfile as if it were a string of
bytes.
Physicalfiles provide severalimportantadvantages:
.

An applicationcan havedirect control over a device.

This direct control providescompleteflexibility. For example,an applicationcan
interpret volumescreatedby other systems.

An applicationcan conservememoryand still be ableto communicatewith devices
that do not need the powerof namedfiles. Examplesof suchdevicesincludeline
printers,displaytubes,plotters,and robots.

The disadvantages
of physicaltiles, as comparedto namedîjles,are that hierarchicalîile
structuresand accesscontrol are not available.

1.7.3 StreamFiles
Streamfìlesprovide a meansof intertaskcommunication.Sometaskscan write into a
stfeamlile while other tasksread from it concurrenrly.Srreamfiles useno devicesand
provide no accesscontrol. They are implementedin memory.

l-,1

Basicl/O Uset'scuide

FEATUR.ES
OF THE BASICI/O SYSTEM

1.7.4 RemoteFiles
The BasicI/O Systemsan alsoaocessremotefiles throughiRMX-NET. For more
information on accessingremote files, consult the |RMX Networking SoffÀ)arcUser'sGuide.

1,8 FILESHARING
ANDACCESSCONTROL
The BasicI/O Systemprovidesyour applicationwith the ability to sharefiles and,in the
caseofnamed files, to control accessto the files.

1.8.1 FileSharing
In a multitasking
system,
it maybe usefirlto haveseveraltasksmanipulating
a ffe
sìmultaneously.
Consider,
for example.
processing
a transaction
systemin whicha large
numberof operators
concurrently
manipulate
a commondatabase.If eachterminalis
drivenby a distincttask,the onlywayto implementan efficienttransactìon
systemls to
havethe rasksshareaccess
ro the databasefile. TheiRMX II OperatingSystemallows
multipletasksto concurrently
access
thesamefile.

.8.2AccessControl
A-lsousefulin a multitasking
systemis theabilityto controìaccess
to a file. For instance,
supposcthat scvcralcnginccringdepartmentssharea computer. an engineerin one
departmentmay want to reservefor himselfthe ability to deletehis files,while ailowing
peoplein his departmentto write and read his file, and peoplein other departmentsto
only read the files. The Basicl/O systemnamedfiles provideyour applicationswith this
kind of accesscontrol.

1.9 SEPARATION
OF FILELOOKUPAND FILEOPENOPERATIONS
Many operatingsystemswastevaluabletime by lookingup a file wheneveran application
tries to open one. The BasicI/O Systemavoidsthis by usinga specialtype of object
(caled a connection)to representthe bond betweenthc file and a program.
Wheneveryour applicationsoftwîre createsa file, the BasicI/O Systemreturnsa
connectìon.Your applicationcan then usethe connectionto open the file without
sufferingthe expenseof havingthe BasicI/O Systemlaokup the file. Even whenyolrr
applicationwantsto open an existingfile, the àppÌicationcan presentthe connectionand
blpassthe file lookup process.
There are severalother beneiitsassociated
wìth connectionobjects.In the caseof named
filcs, conneclionscmbodyaccessrightsto the fìle. This meansthat ac.cess
need orìlybe
computedonce(whenthe connectionis created)rather than eachtime the file is opened.

BasicI/O User'sGuide

l-5

FEATT]RES
OF THE BASICI/O SYSTEM

A secondbenefit ofconnectionsis that severalconnectionscan simultaneously
existfor
the samefile. This allowsseveraltasksto concurrentlyaccessdifferent locationsin the
file. This is possiblebecauseeachconnec[ionmaìntainsa file pointer to keeptrack of the
withinthe file,wherelhe taskis readingor wriring.
locarion,

1.10 CONTROL
OVERINTERNAL
FRAGMENTATION
OF FILES
When informationis storedon a massstoragedevice,spaceis aliocatedin blocks.ather
than one byte at a time. Theseblocksare calJedgranules,and rhe block sizeis called
granularity.There are three kinds ofgranularity that are jmportant.
devicegranularity
The devic€granularityis hardwaredependentand variesamongindividualmassstorage
devices.lt representsthe minimum amountof dala that the devìcecan read or write
during one l/O operation. For disk med;a,a devicegr:rnuleis caùeda sector;therefore
the devicegranularìtyis the scctorsize. Eachbuffer that the BasicI/O Systemuseswhen
readingandwritingdatais equalin sizeto the devicegranularity.
volumegranularity
Volume granularityis a muìtipleof the devicegranularity. It representsthe mrnrmum
amountof spaccthat canbe allocate.lto a file ar one tinle. Tlìe BasicI/O Systenìus€san
a]gorithmbasedon volumegranularitywhen decidingwhereon the volumeto allccate
this space Yorì snecifythe volumegranularitywhenyou lbrmar the volume.
lile granùlaritJ
File granularityis a multiple of volLrmegrarrularitywhich specifiesthe actualamountof
spaceon the massstoragedevìcethat the Basicl/O Systemallocatesto a file at one time.
You assignthe fiJegranularityon a per-file basiswhenyou invokeA$CREATE$FILE to
createthe files.
Bl' selectinSthe proper granularityvalues,you can minimizefragmenrarionofyour
volumes. Use the followingguideìineswhen selectingthesevalues:

Ì-6

Devicegranularitydepcrcìson hard*,are.Ifyouf devicesupportsmultiple device
granularities,selectìngthe largervalueusuallygiveshigherperformance.Although
you can obtaingreaterpcrfbrmancc,you may\r'asiestoragcspacedue to a few large
granulescontainingonly a few bytesof data.

For flexiblediskettes,alù'itysset the volumegranularityequalto the device
granularity,unlessyou plan to storemanylarge files on the volume. Even then, don,t
selecta volu[re granularitv largcr than 1K ( 1024byr€s).

BasicI/O User'sGuide

FEATURES
OF THE BASICI/O SYSTENI

For harddisks,setthevolumegranularity
equalto the devicegranularity,
unÌessthe
devicegranularity
is lessthan1K. Thensetthevolumegranularityto lK.
Whencreatinga largefile,assigna largefile ganuÌarityto minimizethenumberof
noncontiguous
blocksthatmakeup thefile. Thisdecreases
thefragmentation
of the
volume.For smallerfiles,setthefile granularity
equalto thevolumegranularityto
minimizewastedspaceon thevolume.

1.11 GLOBALTIME-OF.DAYCLOCK
SomeboardssupPoriedby the iRMX II OperatingSystemhavean on-board,battery
backed-up,time-of-dayclock. The BasicI/O Systemreadsand writes the time of day,
taking advantàgeof this clock feature. The globaltime-of-dayclock is globalìn the sense
that it is the timekeeperfor the entire system.The iRMX II OperaringSystemmaintains
a "local"time-of-dayclock of its own,which is a copyof the globalclock. The globaland
local clockskeep track of two ite s:
.

The current date (day.month,and year)

The currenttime (hours,minutes,and seconds)

The iRMX II OperatingSystemneedstwo time-of-dayclocksbecauseit takesmuch
longer (100 millisecondsand up) to acr:ess
thc globalclock than the local clock
Therefore,the iRMX II OperatingSystemmaintainsthe local time-of-dayclock for irs
date and time needs,and accesses
the globaltìme-of-dayclock only during system
initializationor upon requestliom the operator.
The iRMX ll tsasicl/O Systemprovidestwo systemcallsrhar enableyour applicationsto
read the globaldate and time and setthem io newvalues. Thesesystemcallsare
CET$GLOBAL$TIME and SET$GLOBAIIITIME. I! alsoDrovidesrwo svstemcallsfor
manipularing
the localclo.l: C ET"lTll\4E anrlShT$TlV E.

1.12 DISKINTEGRITY
In anycomputersystem,
therearemanyoccurrences
beyondthecontrolof theprogram
or programmer
thatcancausedamag€to filesor diskvolumes.For example,
power
outages
canoccurjustasa file is beingwrìtten,or marginaldisksectorscansuddenly
becomeunreliable.The Basicl/O System
hasseveralIeaturestlìat enableprogramsto
maintaindiskintegrityanddeterrnine
whetherfiìesor volumeshavebeencorrupted.The
followiDg s€ctiotìsoutlirìe thcse lealures.

Basicl/O User'sGùid€

t-7

r.f.aTtÌRFs oF THF]RASTCt/O SYSTEM

1.12.'lAftachFlags
The Basicl/O Systemmaintainsflagsthat can indicatethe integrity of nameclvolumes
nd namedfiles. Wheneveryou attacha namedvolume,ihe BasicI/o Systemsetsa flag
in the volumelabel to indicatethat the volumeis attached.Lilewise, whenyou attacha
namedfile, thc BasicI/O Systcmsctsa flag in thc fnode (file dercriptornode) file to
indìcatethat the file is attached.When you detacha volumeo. file, the BasicI/O System
cìerrs the associat€cl
flag,indicatjngthat the file or volumewassuccessfully
detached.
Although the Basicl/O Systemdoesn'tchecktheseflagsto determinefile or volume
iotegrity,you can checkthe conditionof a volumeby invokingthe
A$GET$FILE$STATUSsystemcall.
The BasicI/O Systemrkresn'tprovidea systemcall for checkingthe file flag. However,
you canwrite your o\ynpfogramsto checkthis flag,or you can usethe Disk Verificatior
Utility to examinethe înode file.

1.12.2FnodeChecksumField
The BasicT/O Systemusesthe fnodefile to keeptrack ol everynamedfile on a volume.
The fnode îile lists suchinformàtionas the file name,the creationand last modificstion
dates,and the location of everydisk sectorthat makesup the file. Wheneveryou accessa
file, the BasicI/O Systemusesthe fnodefile to determinethe file's ìocationon the
volume. Wlenever you create,modiry,or deletea file, the BasicI/O Systeù modifiesthe
fnode file to matchthe changesyou made.
When the last connectionto the file is deleted,the BasicI/O Systemwrites to the inode
file, and it alwayscalculatesa checksumand writes that valuein one of the fìeldsof the
fnodefile. This checksumcan be usedto determineirhether any data errors occurred
whcn the BasicI/O Systemwrote the frode file. AlrhouBhthe BasisI/O Systemdoesn'r
calculateanotherchecksumand compareit againstthe originalwhenit next readsthe file,
your programscan usethe checksumfield !o determinevrhetherthe fnode file has
becom€corrupted. DISKVERIFY and SHUTDOWN can be used.

1.12.3GettingandSettingthe BadTrack/Sector
Information
It is not uncommonfor a hard disk to havea few secîorsor tracksthat cannotreliably
store information Mrny of these(liskshavea recordofthese bad trackswritten on the
second-highest
cylinderof the disk. When rhe Basicl/O Systemformatsa disk,it uses
this had track/sectorinformationto assignalternaterracksor sectorsfor the bad
tracks/sectorslisted. The A$SPECIAL systemcall alsohls the ability to retrieveand set
the bad track/sectorinformationon a volume. One subfunctionallowsyou to retrievethe
currentìist of defectivetracksor sectors.Aiother subfunctionenablesyou to set up a
new bad track/sectorlist.

l -ll

BasicI/O Useascùide

2.1 INTRODUCTION
Beforeyou usethe BasicI/O System,you must undentand severalfundamentalmncepts.
Someof theseconceptswere presentedin Chapter2. The remainingconceptsare
.

Systemprogrammers

Devicecontrollersand deviceunits

Volumes

o Files
.

Connections

The followingsectionsexplaintheseconcepts.

2.2 SYSTEMPROGRAMMERS
There are two programmingrolesassociated
with the iRMX II OperatingSystem.One
roÌe jnvolvesusingsystemcallsand objectsthat affectonly your own iRMX ll job, while
the other role involvesmanipulatingsystemresourcesand characteristics.Thesetwo
rolesare calletÌapplicalionprogrammingand systemprogramming.
Although the roleshavedifferent names,separatepeopleare not required. One
individualcan perform botlr roles. The reasonfor the distinctionis that the actionsof the
systemprogrammeraffectthe perfoÍmanceand securityof the entjre system,whereasthe
actionsof the applicationprogrammerhavea more limited effect.
The Extended.íRMX II BasícI/O SystenCalls ReferenceManual givesyou several system
call descriptionsthat beginwith cautionnotices.Thesesystemcalls,if misused,can have
seriousconsequences
for an applicationsystem.Therefore,you shouldconsiderthese
systemcallsto be resered for the €xclusiveuseof systemprogrammers.

2.3 DEVICECONTROLLERS
AND DEVICEUNITS
You are probabÌyfamiliar lvith îhe notion of a device;a hardwareentity that taskscan use
to read or write information,or to do both. Deviceshclude fleúble diskettedrives,line
printers,terminals,card readers,and the like.

Basic l/O Use/s Guide

I'LNDAMENTAL CONCEPTS

In the iRMX II environment,it is convenientto make a distinctionbetweendevicesand
the hardwareinterfacesthat communicatedjrectlywith an iRMX Il applicationsystem.A
hardwareentity that talks djrectlywith iRMX Il softwareis a devicecontroller. Devices
suchas thosenamedin lhe previousparagraphare deviceunits. T)?ically,a device
controller actsas an interfacebetweeniRMX Il aDDlication
softwareand severaldevice
units. For example,an iSBC 214 WinchesterConirollcr boardactsas all irtterface
betweenapplicationsoftvr'are
and from one to four Winchesterdisk drives(deviceunits.)

2.4 VOLUMES
A volumeis the medium usedto storethe informationon a deviceunit. For example,if
the deviceunjt is a flexibledisk drive,the volumeis a disketteiif the deviceunit is a
bubblememoryboard,the volumeis the blrbblememory;and if the deviceunit is a multiplatter hard disk drive, the volumeis the disk pack.

2.5 FILES
Someoperatingsystemstreat a lile as a device,while otherstreît a iiie as information
storedon a device.The BasicI/O Syst€mconsidersa file to be information.
The Basicl/O Systemsupportsfour kinds offiles, and eachhascheracteristics
that make
it unique. RegardlcssoI lhc kind of file. rhe BasicI/O Sysremprovidesinformationto
applicationsas a stringofbytes, rather than as a collectionof records.

2.6 CONNECTIONS
FORTASKAND
DEVICE.UNIT
COMMUNICATION
In complexenvironmentssuchas thosesupportedby the iRMX II OperatingSystem,
severallayersof softwareand hardwaremustbe bound togetherbefore communication
betweenapplicationtasksand deviceunits cancommence.Figure 2-1 showstheselayers.

2-2

BasicI/O User'sGuide

FUNDAMENTAL
CONCEPTS

Figure 2-1. l,ayersof InterlhcingBehreenTssks ond a Device

2.6.1 Interlayer
BondsPreceding
Initialization
The bond betweena devicecontrollerand the deviceunits that it controlsis a physical
bond,usuallyin the form of wires or cables.A deviceclriveris bound to devicecontrollers
by data residingin a data structureknown as a DeviceUnit Information Block IDUIB).
You supplythe data for the DUIBS wher you userhe InteractivcConfigurationUtilìty
(ICU) to configurethe OperaringSystem.
When your applicationstartsup, there is a gap betweenthe applìcationsoftwareand the
file drivers,and anothergap betweenthe file driversand the devicedrivers. Figure 2-2
illustratesthis situaiion. The new element,shownin the figure as the configuration
interface,is the "glue"that providesthe final bonds.

RasicI/O User'scuide

FIINDAMENTAI, CONCEPTS

2.6.2Post-lnitialization
Bond- theConfiguration
lnterface
The configurationinterfaceprovidestwo kindsof systemcalls. Beiore a task can usea
file, both of thesekinds of callsmustbe invoked,and eachDroducesa connection.These
connectionsare calleddeviceconneclionsand file connectiòns,and severalof them are
shownin Figure 2-3 as conduitsand wiresthroughthe conduits,respectively.

Figùre2-2. Schematic
of Software
at InitializalionTime

2.6.2.1DeviceConnections
lasksemploytheconfiguration
interfacefirstby callingthe
A$PHYSICAI$ATTACH$DEVICE
systemcall,whichreturnsa tokenfor an iRMX lI
objecttlpe calleda deviceconnection.Thisdeviceconnection
is the apptication,s
only
pathwayto thedevice.Moreover,therecanbe onlyonedeviceconnection
benveen
a
dcvicc unit and all of the application tasks that lleed 1()usc the device.

BasicI/O User'sGùide

FUNDAMENTAL
CONCEPTS

Because
the deviceconnection
is socenlrallyimportantto theapplication,
onlytasks
writtenby a systemprogrammer
shouldcallA$PHYSICAL$ATTACH$DEVICE.
Sucha
task could makc the deviceconnectionavailableto applicationtasksselecrivelylry sending
it to certainmailboxesor by catalogingit in cerîainobjectdirectories.Or, to ensurethat
all required deviceconnectionswill be availabìeto all of the applicationtasksthat nccd
them,the systemprogrammercouldprovide an initializationtask that c.eatesall of those
deviceconnectionsand catalogsthem in the root objectdirectory.
If and when the deviceis no longerneededby the application,an appropriatetask can call
A$PHYSICAI-$DETACH$DEVICE to deletethe deviceconnection.
2.6.2.2 File Connectlons
When an applicotionlask is readyto usea deviceunit, it must usc the deviceconnection
for that deviceunit to obtaina file connectionobject,which is a connectionto a particular
file on that der,,ice
ùnit llow the taskdoesthis dependsonwhether the file alreadyexists.
If the file alreadyexists,the task usuallycallsA$ATTACH$FILE, althoughit can alsocall
A$CREATE$FILE. If the file doesnor yet exist,rhe task mustcall A$CREATE$FILE.

BasicI/O Usecscuide

2-5

FUNDAMENTAI,
CONCEPTS

Figure2-3. A Systemwith DeviceandFile Connections

NOTE
trven thougha îask can cal A$CREATE$FILE to obraina file connection
for a file that alreadyexists,it is not a good ideafor a task to use
A$CREATE$FILE unlessthe task is certainthat rhe filc docsnot yct
exist. There are two reasonsfor this.

2-6

BasicI/O User'sGuide

FUNDAMENTAL
CONCEPTS

Filst, if a namedfile exisrs,then callingA$CREATE$FILE ro obtain a
connectionto the file might càusethe file to be truncated. This could
causeproblemsfor taskshaviìg oth€r conncctionsto that file, becauselhe
file pointers(discussed
later in this section)for thoseother conne.tions
are not affected,eventhoughthc cnd-of-filemarker might be movcd
closerto the beginnitg of the file
Second,if a file exisasas eithet a physicalor streamfile, then it doesnot
matter whethernewconnectionsto the file are obtainedby a call to
A$CREATE$FILE or A$ATTACH$FILE. However.it is Dossiblethat
the codethat doesthi. wil someda)be usedto crearea connection
to a
namcd file, and as you can see,this can causeproblenìs.
Unlike deviceconnections,there can be multiple file connectionsto a singlefile. Thjs
allowsdifferent tasks,if necessary,
to havedifferent kinds of accessto the samefile at the
sametime, as the next paragraphshows.
AJter receivinga lile connection,a task caÌlsA$OPEN to open the connection.In the call
to AgOPEN, the task specifieshow it intendsto usethe lile connectionand how it is
willing to sharethe file with other tasksusingother connections,
by passiagthe following
.

An open-modeindicator
The open-modeindicatortellsthe BasicI/O Systemhow your applicationis goingto
use the connection.This parametercan specilythat the connectionis open for
readingonìy,for wrìting only,or fbr both readingand writing.

A sharc-modcindicator
The share-modeindicatorspecifieshow other connectionscan shareîhe file with the
connectionbeingopened. I his parametercan specifythat there can be no other open
connectionsto the iile, that other connectionsto the file can be op€nedfor reading
only,that orher cornectionsro rhe file can be openedfor writing only,or that other
connectionsto the file can be openedfo. both readhg and wrìting.

For eachopen file connectionto a random-access
deviceunit, the BasicI/O System
maintainsa file pointer. Thìs is a pointer that tells the BasicT/O Sysremrhe logical
addressof the bytewherethe nextI/O operationon the file is to begin. The logical
addresses
of the bytesin a iile beginwith zero and increasesequentiallythroughthe
entire file. Normallythe pointer for a file connectionpoints at the nextlogicalbyte after
the one most recentlyread or written. However,a task can usethe file connection,if
neeclbe, to modirythe file pointer by meansof the A$SEEK systemcall.

Basicl/O l)ser'sCuide

FUNDAMENTAL
CONCEPTS

2.6.2.3 SomeObservalionsabout Devicesand Connections
Figure2-3is quitedetailedandshowsmostofthe situations
thatarepossible
for device
units and file connectionsto them. In particular,you can observethe following:

2-8

Deviceconnectionsextendfrom the applicationsoftwareto the individualdevice
units,and eachpassesthroughone and only one file driver.

There is only one deviceconnectionto eachconnecteddevice,and multiple file
connectionscan sharethe samedeviceconnection.

Different deviceùnits with the samecontrollercan be connectedvia different file
drivers.

Taskscan shareaccessto the samedeviceunit throughthe physicalfile driver, and
they can shareaccessto the samefiles on the samedeviceunit throughthe namedfile
driver.

There is only one deviceconnectionthroughthe streamfile driver,reflectingthe fact
that a singlc,logicaldevicecontainsall streamfiles. There can be addilionalstream
files in the applicationif more are needed.

The configurationinterface,which is depictedas a pile ofconduits,is off to one side.

All but one of the deviceunits are connected.The unconnecteddeviceunit is still
separatedfrom the applicrtionsofrwareby the configuraîioninterface.

BasicI/O User'sGuide

CHAPTER
3
NAMED
FILES

3.1 INTRODUCTION
Namedfiles are intendedfor usewith random-access,
secondarystoraliedevicessuchas
disks,diskettes,anclbubblememories.Namedfiles provideseveralfeaturesthat are not
providedby physicalor streamfiles. Thesefeaturesinclude
.

Multiple Files on a SingleDevice

Hìerarchical
Nalìing of FiÌes

AccessControl

Extra Data in a File's Descfiùor

Thesefeaturescombineto make namedfiies extremelyusefulin systemsthat support
more than one applicationand in applicationsthat requiremore than one file

3.2 MULTIPLE
FILESONA SINGLEDEVICE
As shown in Figure 3-1, your application can use named files to implement more thsn one
lle on a single devicc. This can be very useful in applications requìring more than one
op(ratnr, :Uch r\ lr nn5.t.tiunptoiessilg \)stem5.

3-3 HIERARCHICAL
NAMINGOF FILES
Th€ iRMX lI n{med fles featureallowsyour application!o organizeits files inro a
numberof tree-likestructuresas depictedin Figure3-1. Eachsuchstructure,calleda file
tree, must be containedon a singledevice,and no two fiìe treescan sharea device. In
other words,if a devicecontainsany namedtiles,the devicecontainsexactlyone file tree.
Namedfile treesmust alsofit on a singlevoÌume.

BasicI/O User's Guide

f,-1

\MEI) FILES

-;;;-oúÍj
I---T-

;l
L

]

i
l_l

l__l

Iigure 3-1, Exampleofa Named-File
Tree

Eachfile tree consistsof two caîegoriesof files-data files and di.ectories. Data files
(which are shownas trianglesin Figure3-1) conîainthe informaîionthat your application
manìpulates,suchas inventories)accountspayable,transactions,
text,sourcecode,or
objectcode. ln contrast,dìrectoryliles (shownas rectangles)containonly pointersto
olher files or direcrori€s.The purposeof the dilectoryfiles is to provideyou with
flexibiliryin organizingyour file structure.

BasicI/O Usefs Cuide

NAITEDFILES

To ilÌustraterhis flexibility,take a closelook at Figure 3-1. This figure showshow named
liles can be usefulin multi-usersystems.Figure 3-1 is basedon a collectionof
hypotheticalenginecrs*,ho work {or three d€paltnìenrs(Dcparrncnts 1, 2 and 3). Each
engineeris responsiblefor his own 1ììes.This multipersonorganizationis rellectedin îhe
file tree. The uppermostdìrectory(calledthe device'sroot dirccrory)points to three
"departmentdire€tories."Each departmentdiectory points to several"engineer's
directories."And the engineerscan organizetheir files as theywish by usingtheir own
diectories.
Each file (directoryor data) hasa uniqueshortestpath connectingit to the root directory
of the device. For instance,in Figure3-1,the lile calledSIM-SOURCE hasrheparh
DEPTI/BILL/SIM-SOURCE. This notion oi "path"re8ectsrhe hierarchicalnarureof
the named-filetree.
Anolher characteristicof hìerarchicalfile namingis rhat rhereis lesschancelbr duplicate
file names. For example,note that Fieure3 I containsdirectoriesfbr two individuals
namedBill. (Thesedirectoriesare on rhe extremeieft and right of the third level of the
figure.) Even if the rightmostBiìl had a dîta file with the file nameof SIM-oBJECT, its
path would differ from that leftmost Bill's SIM-OBJECT. Specifically,the lefrmostSIMOBJECI is identifiedbyi
DEPTl/BILL/SIM-OBJECT
whereasthe rightmostSIM-OBJECTwouldbe identilied by:
DEPT3/BILL/SIM-OBJ ECT
Wheneveryour applicationmanipulateseither kind of namedfile, the îpplication must
tell the BasicI/O Systemwhich file is to be manipulated.There are severalwaysto
specifya particularnamedfile to the BasicI/O System,all ofwhich involveconnections
andpaths.

3.3.1 Connections
Onceyou havea connectionto a parîicularnamedfile, you can usethe connectionas the
PREFIX pa.ameterof any systemcall. If, in the samecaì1,you set the SUBPATTI
parameterto NIL or SELECTOR$OF(NIL),the BasicI/O Systemwill ignorethe
SUBPATH and useonly the PREFIX ro find that particularflle.

BasicI/O User'sCuide

N A NÍF:I) FILES

3.3.2Paths
If you do not havea connectionto the file, you can specilythe file by usingits path. To do
lhis, build an iRMX II string. (An iRMX lI stringis a representationofa characterstring.
To representa string of n characters,you must usen+ l consecutivebytes. The first byte
containsthc charactercount,n. The followingn bytescontainthe ASCII codesfor the
characters,in the sameorder as the string.) This string is calleda path name. Then use a
pointer to this path nameas the SUBPATH parameterin the systemcall,and usethe
deviceconnectionas the PREFIX parameterin the systemcall.
For example,ifyour namedîile tree is on Drive l, and ìt hasthe path name
DEPT2/HARRY/TEST-RESULTS, you can specii, the file by usingthe devrce
connectionlbr Drive 1 as the PREFIX parameterand a pointer to the path nameas the
SUBPATH parameter-

3.3.3 Prefixand Subpath
Onceyour applicationhasobtaineda connectionto a directoryfile within a namedfile
tree, the applicationcan usethat conneclionas a basisfor reachingall files thaî descend
from the directory.
For example,referringagainto Figure3-1,supposeyour applicîtion hasa connectionto
Directory DEPTI/TOM. The applicationcan refer to D:ìî, File BATCH-l by usingboth
the PREFIX and the SUBPATH parameters.The applicationshouldusethe connection
to DirectoryDEPTl/TOM as the PREFIX, and it shouldusea pointer to a subpathname
as the SUBPATH. The subpathnameis a stringthat connectsDirectory DEPIl/TOM to
Data File BATCH"1. For îhis example,the subpathnameis TEST-DATA/BATCH-1.

3.3.4 DefaultPrefix
Within one iRMX IIjob. most refercncesto a namedfile tree a.e generallyconfinedto
one branchof the tree. For example,in Figure3-l, Tom will usuallyaccessthe files in his
directorymore frecluentlvthan liles outsideof his directory. Recognizingthis clustering,
lhe BasicI/O Systemprovidesthe notion of defauÌtprefix.
The Basicl/O Systemallowsyour appÌicationro spccifyonc dcfault prefìx for each
iRMX II job. A defaultprefir is a connectionto a directoryat the headof the most
commonlyùsedhrrnch in vour nemedfile tree. For instance,in Figùre 3-1,Tom's
appìicationwould probablyuseíl connectionto Directory DEPTl/TOM as the default
prefir. To use the defaultprefil(,the applicationsetsthe PREFIX pa.ameterto NIL or
SELECTOR$OF(NIL),

BasicI/O Useis Gùide

NAMEDFILES

A defaultprefìxprovidesa job with two advantages.First, by providinga referencepoint
within a namedfile tree, it alLowsyour applicationto usesubpathnamesinsteadof path
namcs. Ifyour trcc is severallevelsdeep,thìs can saveprograrnrningtinre during
development.Second,and more significantly,a defaultprefir providesa meansofwriting
generalizedapplicationcodethat canwork at any ofseveral locationswithin a trcc.
Consideran example.Supposethat an assembler(implementedas an iRMX IIjob) uses
a defaultprefir to find a locationin a namedfile tree. The assemblercould then Ltsea
subpathnameof TEMP to find or createa temporarywork fiìe. Before an application
invokesthe assembler,it setsthe defaultprefix of the assemblerjobto a directoryin the
application'snamedfile tree. This allowsmore than onejob to invoke the assembler
concurrenîlywithout the risk ofsharing temporaryfiles.
The BasicI/O Systemkeepstrack of a job's defaultprefix by usingthejob's otrject
directory. Wheneveryour tasksusethe SET$DEFAULT$PREFIX systemcall to specify
a connectionas beingthe default,the BasicI/O Systcmcatalogsthc conncctionundcr thc
name$ in thejob's objectdirectory.

3.4 CONTROLLING
ACCESSTO FILES
In most environmentswherefiles are sharedamongmultiple users,it is necessaryto have
a meansof controllingwhich usershaveaccessto $hich files. Among userswhohave
accessto a givenfile, it is frequentiynecessary
to grant different kinds of accessto
different users.The iRMX II OperatingSyste providesthis control \ identifyingusers
with user IDs and embeddingaccessrìghtsfor theselDs into the files. This secîion
describesthe userID and file accessmechanisms.

3.4.1 Usersand UserObiects
The iRMX II OperatingSyst€musesthe conceptof "user"to correlrte file a.cessto
peopleor to iRMX II jobs. But the precisedefinition of "user"dependson îhe nature of
your application.
Ifyour applicationallowsseveralpeopleto enter information(at terminals,for example),
you might want to considereachperson(or smallgroupofpersons)a user. This allows
eachindividual(or smallgroup)to maintainaccessdifferent from other indivicluals(or
smallgroups).
Alternatively,ifyour applicationdoesnot interactwith people(or allowsonly one person
to interact),you mighl wish to considereachiRMX IIjob as a user. This setupwould
allowyour applicationto control the îiles that eachjob can access.

BasicI/O Uscr's Guide

l-5

N \\IID I'ILES

In more generalterms,the set of entitiesthaî manipulatenamedfiles in your systemis
the sct of all users. lî you want all of theseentitiesto be ableto accessany file, you can
considerthem to be a singleuser. Flowever,ifyou want to distributedifferent acressto
Lììllerentcollectionsoflhese enlities,you musrdivide the enaitiesìnto subsets,eachof
which is a separateuser.
For cxemple,ìook at Figure 3-1. As mentionedearlier,all engineersare responsiblefor
their own files. lf engineerswant Io haveuniqueaccessîo their files (perhapspermitting
no one elseto use their files),eachengineermustbe a separateuser. Flowever,if all
engineersare wiLlingto give uniform aocessto other membersof the department,then the
oePartmenlcan be a separateusef,
3 . 4 . 1 . 1U s e rl D s
A userlD ìs a l6"bit numberthat representsany individualor collcctìonof indiriduals
requiring a separateidentity for the purposcofgaining accessto files.

3.4.1.2UserObjects
The BasicI/O SystemLrses
a specieltypeof objectcalleda userobjectwhen determining
accessrights to files. A userobjectcontainsa list of one or more userIDs. Wlten a tesk
altemptsto manipul{tea file,it mustsupplythe îokenfor a userobject. lo determilre
access,
îhe OperatingSystemcomparesrhe IDs in the supplieduserobjectwith
ìnformation
containedin the file itself.
To understanduserobjects,consjderan applicationin which everypersonwho accesses
the systemis a separateuser. In this sìtuation,everypersonwould havea separateuser
object. The userobjecl represenlsthe person.
'l

he first lD in the userobjectis the ownerID. This is the ID of the userwhom the object
represents.lf you think of a userobjectas a person,the ownerID representsthe nameof
that person. When a personcreatesfiles,the OpcratingSystemautomaticallyembedsthe
ownerID of that person'suserobjecainto the file, atlowingthat personautomaticaccess
to rhe lile.
The IDs that follow rhe ownerlD representadditionalkilds of accessthat the personhas.
For exampÌe,peopleoften belongto organizationssùchas athleticclubsand fraternal
croupswhich distributeidentitycardsto their members.To participatein the
organization,peoplemust showtheir ìdentitycardsto prove they are members.The user
IDs that follow the ownerlD servethe samepurpose. They jdentily the personas one of
a selectgroup,all ofwhom havethe sameaoressto a certainset of files.
The Basicl/O Systemhasthree systemcallsthat rnanipulateuser objects:
.

3-6

CREATE$USER createsa userobjectand returnsto the calìingtask a token for that
userobject.

BasicI/O User'sGuide

NAMEDFILES

DELETE$USERdeleres
a userobjeo.

INSPECT$USER
returnsto thecallingraskthelist oflDs in theuserobjectspecified
in thecall.

3.4,t.3 OefaultUserOblectFor a Job
Mostl/O operations
performedwithina particulariRMX lljob areperformedon behalf
of oneuserobject.Recognizing
this,theBasicI/O Systemallowsyourapplication
to
designate
a defauìtuserobjectfor eachjob.Wleneveryourapplication
invokesa Basic
I/o Systemcallon behalfofthedefaultuserobject,the application
canuse
SELECTOR$OF(ML)asrherokenfor the"user"paramerer.The Basjcl/O System
recognizes
the SELECTOR$OF(NIL)
asrefeúingto the defaultuser.
TheBasicl/O Systemprovidestwo systemcallsto manipulate
a job'sdefaultuser.
SET$DEFAULT$USER
canbeusedeitherto changean existingdefar.rlt
userobjector,
in thecaseofjobshavingno defaultuserobject,to establish
one.
GET$DEFAULT$USER
canbe usedto ascerrain
rhedefaultuserfor a job.
The BasicI/O Systemusesthejob'sobjectdirectoryto keeptrackof thejob'sdefaultuser
object.Whenever
oneofyoùr taskssetsor getsa defaultuserobject,the BasicI/O
Systemeithercatalogs
or looksup theentryfor thedefaultuserobjectin the object
directory.It usesthenameR?IOUSERto referto the defaultuserobject.To prevent
problems,
youshouldconsiderR?USERto be a reseraed
name,andyoushouldavoid
usingit.

3.4.2 Typesof Accesslo Files
Eachofthe two kindsofnamedfiles-directory
îilesanddatafiles-canbeaccessed
il four
differentways.
Everydirectoryfile canporentially
be accessed
in oneor moreofthe followingways:
Delete

Deletethe direcroryfile withA$DELETE$FILE.

List

Obtainthecontentsofthe directoryfile withA$READ or
A$GET$DIRECTORY$ENTRY,

Add Entry

Add entriesto the direoorywithA$CREATE$FILE,
A$CREATE$DIRECTORY,
or A$RENAME$FILE.

ChangeEntry Changetheaccess
rightsof fileslisredin the directorywith
A$CIIANGE$ACCESS.

BasicI/O UsePsGuide

\,\MET' FILES

Every data file can potentiallybe aclessedin one or more ofthe followingways:
Delete

Delete rhe file wirh A$DEI-ETE$FILE or renameihe file with
A$RENAME$FILE.

Read

Readthe file wìth A$READ.

Append

Add informationto the end of the file with A$WRITE.

Update

Changeinformationin the file with A$WRITE or drop informationwith
A$TRUNCAI'E,

A uscr'saccessrights to a particularfile dependon the accesslist associaiedwith that file.

3.4.3 FileAccessList
For eachnamedfile (data or directory),the BasicI/O Sysremmaintainsan accesslist
which definesthe users$ho haveaccessand their acess rights. Each arcessljst is a
collcctionof up to three ordcredpairs haviDgthe folltì
ID, accessmask
'Ihe

ID portion is a userID- The lìst of userIDs defìnesthe userswho can accesstlte file.

1'heaocessmaskportion definesthe kind of file aqjessthat the correspondinguserhas.
An aoccssmuskis a bye in which inclividualbis representthe vaaiouskinds of access
pcrmitted or deniedthat user. When sucha bit is set to f. it signifiesthat the associated
kind of (ccessis permirted. Whcn sct to 0, the bit signifiesrhat the associatedkind of
accessis denied.
The associationbetweenthe bits ofthe accessmaskand the kinds of accessthey control
are as follows(wherebìt 0 is the least-significant
bìt):
Bit

DirectoryFiles

Data Files

0
1
2
3

Delete
List
Add Entry
ChangeEntry

Delete
Rcad
Append
Update

The remainingbits in the accessmaskhaveno significance.
For example,an ^ccesslist for a data file might look ]ìke the following:
5 B 3 l 0 0 0 0 1l10
9F2C 00000010

3-8

BasicI/O User'sGuide

NAMED FILES

wherethe ID nùr'nbcrs(left column)are in hexadecimaland the accessmasks(right
column)are in binary. This meansthaî the ID number5B31hasread,append,and
updateacressrights,while thc lD numbcr 9F2Chasthe read accessright.
The first entry in the file's accesslist is placedthere automaticallyby the BasicI/O
Systemwhen it createsthe file. The ID po.tion of that entry is the first ID numberin the
userobjectspecjfiedin the call îo A$CREA-IE$FILE. That ID is known as the ownerID
for the file. The accessrightsportion is suppliedas a parameterin the samecall.
Taskscan alter the acresslist of a file by meansoîthe ASCIIANGE$ACCESSsystem
call. With A$CHANGE$ACCESS,you can add or deleteID-accesspairs,and you can
changelhe accessrighrsoflDs alreadyin the accesslist.

NOTÉ,
The userwhoseID is theownerID for a file hasoneadvantage
overother
users.Onlya file'sownercanusetheA$CIIANGE$ACCESS
systemcall
to modifythe file'saccess
list withoutbeinggranieder?licitpermission
to
do so.

3.4.4 ComputingAccessfor FileConnections
'Whenever
a taskcallsA$CREATE$DIRECIORY,
A$CREATE$FILE,
or
A$ATTACH$FlLE,thc Basicl/O Systemconstructs
an access
maskandbindsit to the
file connection
objectreturnedby thecall. Thisaccess
maskis constantfor thelife of the
connection, even if thc acccsslist for the file is subsequentlyaltered. When rhe
connection is used to manipulaaethe file, the accessmask for the connection deterúines
how the file can be accessed. For example, if the computed accessrigits for a connection

to a data file do not inclurleappendingor updating,then that connectioncannotbe used
in an invocationofA$WRITE.
When a task callsA$CREATE$DIRECIORY or A$CREATE$FILE, the accessmask
for the connectionis the sameas the accessmaskthat the task suppliesin the "access"
parameterof the systemcall. However,when a taskcallsA$ATTACH$FILE, the Basic
I/O Systemcomparesrhe userobjectspecifiedin the "user"parameterwìth the file's
accesslist and computesan aggregatemask.
Figure 3-2 illustratesthe algorithmthat the BasicI/O Systemusesdrjringa call to
ASATTACH$F[LE. As the figure shows,the BasicI/O Systemcomparesthe IDs in the
specifieduserobjectwith the IDs in the file's accesslist. The accessmaskscorresponding
to matchingIDs are logicallyORed, forming an aggregatemask.

BasicI/O User'sCùide

3-9

NAMEDFILES

Figùre 3-2. Computidgthe AccessMask for a File CoÍnectioú

Normally,the BasicI/O Systemusesthe aggregateaccessmaskembeddedin the
connectionto deterùine a task'sability to accessa file. However,there are two
circùmstances
in which the BasicI/O Systemcomputesaccessagain:during
A$CI{ANGE$ACCESSand duringA$DELETE$FILE. When a task invokesone ot
thesesystemcalls,the BasicI/O Systemcomlutes the ac.essto the targetfile (or to rhe
datafile or directoryspecifiedin the "prefix"parameter,if the subpathportion is null). If
the userobjectspecifiedin the systemcall doesnot haveappropriateaccessrights,the
BasicI/O Systemdeniesthe task the abiiìtyto deletethe file or changethe access.

3-10

BasicI/O Usels Guide

NAMEDFILES

NOTE
Whencomputing
access,
theBasicI/O System
checksthe access
onlyto
thelastiile in the specified
subpathandto theparentdirectoryofthe last
file. It doesnot checkthe access
to anyotherdirectoryfilesspecified
in
thepath. If the subparh
is null,theBasicI/O System
checksthe access
to
the file indicatedbythe "prefix"parameter.

3.4.5SpecialUsers
Therea.e twouserIDs thatcanhavespecialmeaningto theBasicI/O System.Oneis
the number0 (thesystemmanager),whichhasspecialmeaningto the BasicI/O Sysr€m.
The otheris thenumber0FFFFH(theWORLDuser),whichcanhavespecialmeaning
basedon the application.
3.4.5.1SystemManagerUser
Ifso indicatedduringtheconfiguration
process,
userID 0 represents
the "system
manager."A userobjectcontaining
thisvalueis privilegedin tworespects.First,whenit
is usedto createor attachfiles,theresultingfile connection
automatically
hasreadaccess
to datafilesandlist access
to directoryfiles. Thisis trueevenifa file,saccess
list doesnot
containan lD-access
maskpairwhoseID valueis 0. Thesecondprivilegegrantedsucha
userobjectis that it cancallA$CHANGE$ACCESS
to changeanyfile'saccess
list.
3.4.5.2WorldUser
By convention, the user ID 0FFFFH represents WORLD (all users in the system). To

implementthis convention,you shouldplacethe lD for WORLD in the list of userIDs for
everyuserobjelt you create. This allowsyour applicationto set asidecertainîiles as
public files,givingeveryoneJìmitedaccess.For example,your file systemmight containa
seriesof utiJities,suchas compilersor linkers,which all usersneedto access.Insteadof
grantingeveryoneaccesson an indìvidualbasis(which is impossibleifyou havemote than
three users),you can grant the userWORLD accessto the fiies. SinceWORLD is on the
ID list of everyuserobject,this grantseveryoneaccessto the files.
As a side eff€ctof ircludilg thc WORLD ID in everyuserobject,any file whoseownerID
is 0FFFFH (WORLD) can haveits accesslist modifiedby anyone.That is, any file
connectionfor rhar file can be usedin a caìl to A$CHANGE$ACCESS.

3.4,6 Example
Ttre following example can help you understand how to use lDs, accessmasks, ac.cesslists,

anduserobjectsto permiteachuserin a systemto haveexactlythe kindsof access
that
you want that user to have

llasic I/O Ilser's Cuide

3-11

NAMED FILES

Relèrringbackto Figlre 3-1,supposethat Tom is to haveall kjnds of accessro rhe file
BATCH-I, that Bill is to haveread and appendaccessonly,and that the membersof
Department2 are to haveread accessonly.
Tom (or whoevercreatesBATCH-I) can arrangefor thesekindsof accessby doing the
fotlowing:
.

Createa numberofuser objects,one for Tom, one for Bill, and one for eachof the
membersof Department2 (Geofge,Harry, and Sam). When crearingrhe user
objects,assignuniqueownerIDs for eachuser. Assumethat the ownealD numbers
are 4000Hfor Tom and 8000Hfor Bill. Assignuniqueowner IDs for eachof the
membersof Department2, but alsoincludea commonuserID (assumeF000H for
this example)as an additionalID in eachoftheir userobjects.)

Use A$CREATE$FILE to createthe file BATCH-I. In rhe call ro
A$CREATE$FILE, úsethe token for th€ userobjectcontainingth€ 4000HID
number and specirythe accessmask00001111B.This call returnsa file connection
that givesits ùser(Tom) all kìndsof accessto BATCH-I. Ar this point, the accesslist
for BATCH-1 hasjust one lD-accessmaskpair.

UseA$CHANGE$ACCESSto add an ID-accessmaskpair ro the accesslis! of
BATCH-I. The ID shouldbe 8000Hand the accessmaskshouldbe 000001108.This
givesBill read and appendaccessto Batch L Now rhc acccssÌist for BATCII-1 has
two lD-accessmaskpairs.

Use A$CHANGE$ACCESSto add a third pair to the accesslist ofBATCH-I. The
ID shouldbe F000H and the accessmaskshouldbe 000000108.This givesthe people
in Dcpartment2 read accessto BATCH-1.

lnform Bill that he can read the contentsof BATCH-1 and appendnew informarionro
it. Desqibeto him the prelir andsuhparh
rharare neededró artrrchBATCH-r,ano
tell him to createa userobjectvr'iththe ID 8000H. Tell him to specifythat userobject
when altachingBATCH-1.

Inform the membersof Department2 that theycan read the contentsof BATCH-I.
Describefor them the prefix and subpathneededto attachBATCH-1, and tell them
to createuserobjectsthat contaìnan entry for the ID F000H. Tell them to speciîy
thoseuserobjectswhen attachingBATCH-1.

When Bill attachesBATCH-1, hc receivesa filc connefiionrhar he can usein callsto
A$READ. He alsocan useASWRITE, providedrhar rhe file poinrer for that connection
is at the end of the file.
When a memberof Department2 attachesBATCH-1, he receivesa lile connectionthat
he can usein callsto A$READ.
Note that this exampleshowsthat one ID numbercan be usedto givecertain accessrights
to an individualand that anotherID numbercan be usedto give differenraccessrightsto
d collectionof indivìduals.

BasicI/O Usels Guide

NAMEDFILES

3.5 EXTENSION
DATA
For cach named file on a randon accessvolurne, rhe Basic T/O Sysremcreares and
maintains a file descriptor on the same volume. The first portion of the descriptor
contains information for the Basic I/O System. The last portion, called cxtcnsion data, is

availableto your operatingsystemextension.You specilythe number (from 0 to 255,
inclusive)ofbytes of extensiondatafor eachnamedfile on the volume,when formatting
the volumewith the FORMAT urility.
Ifyou are writing an operatingsystemextension,and you want to recordspecial
informationin a file's descriptor,you can useA$SET$EXTENSION$DATAto plàcethe
data into the trailing portion of the descriptor.A$GET$EXTENSION$DATA car be
usedto accessthis datawhen it is neededlater.

3.6 SYSTEMCALLSFORNAMEDFILES
Severalsystemcallsrelateto iRMX II namedfiles. Someofthese callsare usefulfor hoth
data and directoryfiles, somefor only one kild of file, and sonre(suchas
CREATE$USER) don'r rclate ro either kind of le.
The followingsectionsbrielly explainthe purposeof eachofthe systemcaÌls. The
descriptionsare groupedby functionrather îhan alphabetically.Thesedescriptionsaae
very brlel. The Ertended iRlvlX II Baic I/O Svstm CaIb RefercnceMarudl conrains
dctailcd dcscriptionsof the calls.

3.6.1 Obtainingand DeletingConnections
Six system calls pertain to obtaining or delcling connections.

A$CREATE$FILE
This call appliesonly to data iiles. Your applicationmust usethis call to createa new
data file, and it can usethis call to obtaina connectionto an exìstingdata file. lf rhe
applicationusesthis call to createa new file, the BasicI/O Systemautomaticallyadds
an entry in the parenrdirectoryfor rhis new file.

A$CREATE$DIRECTORY
This call appliesonly to directoryfiles. Your applicationmust userhis calì to cteaîea
new directoryfile. The caÌlcannotbe usedto oblain a connectionto an existing
directory. Th€ BasjcI/O SystÈnìautoln,llicalyaddsan enlry in rhe parent direcrory
fbr this new directory.

A$A'l'IACH$FILE
This call appliesto both data and directoryfiles- Your applicationcan usethis call to
obtain a connectionto an existingdata or directoryfile.

BàsicI/O fÌser's cuide

NAMED F'ILES

A$DELETE$CONNECTION
This call appliesto both data and directoryfiles. Your applicationcan use this call to
deletea connectionto either kind ofnamed file. This call cannotbe usedto deletea
deviceconnection.

A$PHYSICAL$ATTACH$DEVICE
This call doesnot directlyapplyto either data or directoryfiles. Your applicationuses
this call io obtain a connectionto a device. Even thoughthis connectionis a device
connection,it can be usedas the prefix for the root directoryof the device. However,
usingthis systemcall c.auses
a task to loseits devìceindependence.

A$PHYSICAIJDETACH$DE\{CE
This call doesnot directlyapplyto either data or directoryfiles. Your appJìcationuses
this call to deletea conùectionto a device.

3.6.2UserObiects
Fivesystemcallspertaindirectlyto userobjects.Noneof thesecallsarespecìfically
relatedto dataor directoryfiles. Thecallsare:
.

CREATE$USER
Thiscallis usedto createa userobject.

DELETE$USER
This call is used to delete a user object.

INSPECT$USER
This call is usedto ascertaina userobje,ct'sid and to find out to which groupsthe user
belongs.

SEfiDEFAULT$USER
Your applicationcan usethis call ro establisha defaulruserfor any iRMX Iljob.

GET$DEFAULT$USER
Your applicationcan usethis call to ascertainthe defaultuserfor any iRMX IIjob.

3- 1,1

BasicI/O User'sCuide

NAMEDFILES

3.6.3 DefaultPrefixes
Twocallspertainto defaultpr€fixes,
andneirhcrot thcsccrllspertainsdirecrlyto data
files or directoryfiles. The callsare:
T SET$DEFAULT$PREFIX
Your application
canusethiscallto setthe defaultprefixfor anyiRMX TIjob.
I

GET$DEFAULT$PREFIX
Your application
canusethiscaUto ascertain
the defaultprefixfor anyiRMX IIjob.

3.6.4Manipulating
Data
Eightsystemcallsallowyouto manipulate
the datain a ffle. Fourapplyto bothdirectory
anddatafiles,twoapplyto datafilesonly,andrwoareauxiliarycallsthataid in thedata
manipulation
process.Thesystemcallsare:
.

A$OPEN
Thiscallappliesto bothdataanddirectoryfiles. Befoteyourapplication
canuseany
other system calls to manipLiate file data, the applicetion must open a connection ro
the file. This system call is the only way to open a conneclion.

A$CLOSE

This call appliesto both data and di.ectoryfiles. AJter your applicationhas finished
manìpulatinga file, the applicationcan usethis systemcall to closethe Îile connection.
Your applicationcan elect!o leaverhe file open,lettingthe BasicI/O Systemcloseit
when the connectionis deleted,but there is an advantageto closingcolnectionswhen
they are not beingused.
This advantagederivesfrom the fact that, when a connectionis sharedbetweentwo or
more applications,someof the applicationscan placerestdctionson the mannerof
sharing. For instance,an applicationcan specirysharingwith writers only. By closing
connections,
your appÌicationcan improvethe likelihoodthat the connectionscan be
usedby orher applications.A conne,ction
is not closeduntil all pendingI/O requests
havebeenhandled.
.

A$SEEK
This systemcall appliesto both data and directoryfiles. Wheneveryour application
reads,writes,or truncatesa file, the applìcationmust tell the Basicl/O Systemthe
locationin the file wherethe operationis to takeplace. To do this,your application
usesthe A$SEEK systemcall to positionthe file pointer of the file connection.The
A$SEEK systemcall requùesthat the file connectionbe open.

Basicl/O Usefs Guide

3-r5

NAMED FII,F]S

A$READ
This systemcall appliesto both data and directoryfiles. Your applicationcan usethis
systemcall to read file data from the locationindicatedby the file pointer and place
the data in a memorybuffer. Before usingthis systemcall,your applicationcan use
the A$SEEK systemcall to positionthe file pointer. The A$READ systemcall
requiresthat the file connectionbe open. lt alsorequiresthat the segmentofmemory
to whichyou copythe data be a writablesegment.
The outcomeof this systemcall dependsupon whethera data file or a directory is
beingread. lfyour applicationreadsa datafile, the applicationwill receivedata that
makesup the file. If the applicationreadsfrom a directory,the applicationwill
receivedata that representsthe entriesofthe directory.
Each entry in a dùectoryconsistsof 16bytes. The first two bytesconraina 16-bitfile
descriptornumbercorrespondingto the file descriptornumberassociated
with the
A$GET$FILE$STATUS systemcall in the ÀÍentletl |RMX II Baric I/O Ststem Calk
RekrenceManual. The remaining14b1'tesare the ASCII charactersmakingup the
nameof the file to which the directoryentry points. (A file's nameis the lasr
componentof a path name.) The advantagein usingthe A$READ systemcall to read
a directoryis that your applicationcan obtainseveralentrieswith one operation.

A$WRITE
This systemcall appliesonly to datafiles. Your applicationusesthis systemcall to
copyinformationfrom a memorybuffer and placeit in thc filc. Bcfore usingthis call,
the applicationcan useA$SEEK to positionthe file pointer at the locationwithil the
fiÌe to receivethe information. The A$WRTTEsystemcall requiresthat the file
connectìonbe open. lt alsorequiresthat the segmentof mertory from which you
copy the data be readable.

A$TRUNCATE
This systemcall can be usedonly on data files. Your applicationcan usethis call to
trim informationfrom the end of the file. To do so.the aDDlicationfirst must use
A$SEEKto positiunthÈtile loinrer ar rhefinr hyrero hJdropped.Thcnrhe
applicationinvokesthe A$TRUNCATE call to drop the specifiedbyte and any b)'îes
Ìocatedafter the spccilicdbytc. The A$TRUNCATE systemcall requiresrhat th€ file
connectionbe open.

WAIT$IO
Your applicationcan usethis systemcall afrer callìngA$READ, ASWRITE. or
A$SEEK to receivethe concurrentconditioncodeof the prior systerncall. WAIT$IO
can also return the numberof bytesread or written.

.3-t6

BasicI/O User'scùid€

NAMED FILES

A$UPDATE
Thissystemcallforcesthe BasicI/O Systemto transferdataremainingin internal
bufTers
immediately
to thefileson a device.Your application
canusethissystemcall
to ensurethatall fileson remoiTable
volumeslsuchasdiskettes)
areuDdated
before
the operatorremoves
thevolume

3.6.5ObtainingStatus
'lhere

are two status-related
systemcalls,one for connectionsand one for files. The calls
are A$GET$FILE$STATUSand A$GET$CONNECTION$STATUS.Both of thesecalls
can be usedwilh data files and directorvfiles

3.6.6ReadingDirectory
Entries
There are two systemcallsthat your applicationcan useto read entrìesliom a directory.
The A$READ systemcall (whichcan alsobe usedto read a datalile) wasdiscussed
earlier,under the heaLlirg"Manipulati g Data." Th€ secondsyslemcall is
A$CET$DIRECTORY$ENTRY. This systemcall can be usedonly on dìrectoryfiles,
,rndcan be usedwjthout openingî connection.

3.6.7 Deletingand RenamingFiles
The BasicI/O Systemprovidesone slsterncall for deletingfiles and anotherfor renaming
files. Both of thesecallscan be usedwith datafiles and diectorv files. The callsare:
.

A$DEI-F.TE$FILE
Your applicationcan usethis systemcall to deletedata files and directoryfiles.
Ilovrever,any attemptto deletea directorythat is Dot erìpty wìll result in an
exceptionalcondition.
'lhe
processof deletìnga tile involvestwo stages.First, the applicatìonmust call
A$DELETE$FILE. This causesthe file to be markedfor deletion. The secondstagc,
which is perlbrmedby lhe BasicI/O System,involvesdeciditg when to deÌeterhe file.
The Basicl/O Systemdeletesmarkedliles only after all connectionsto the file have
becn dclctcd. Rcfcr to thc A$DELETE$CONNECTION svstemcall to seehow to
deleteconnections.

A$RENAMESFILE
Your applicationcan usethis systemcall to renameboth data files and directoryliles.
In renaminga file, your appiicationcan movethe file to any directoryin the samc
namedfile tree. For exampìe,you can renameA/B/C to be A/X/C. ln effect,this
examplesimplymovesFile C from Directory B to Directory X. This meansthat your
applicationcan changeeverycomponentof a file's pàth name.

Basict/O User'sGuid€

3 -l 7

\A\tED FILES

3.6.8ChangingAccess
'fhe

BasicI/O Systemprovidesone systeú call to let your applicationchangea file's
accesslist. This call is A$CI{ANCE$ACCESS,ard it appliesto borh darafiles aùd
directories. One rule govemsthe useofA$CHANGE$ACCESS-onIy the owoerofa file
or a userwith changeentry accessto the directorycontainingthe file can changethe file,s
acresslist.

3.6.9 ldentifyinga File'sName
The BasicI/O Systemprovidesa systemcallto leryourapplication
find out the last
component
of a file'spathnamewhentheapplication
hasa connection
to the file. The
systemcallis A$GET$PATH$COMPONENI,
andyoucanuseit on daîafilesand
directories.For an explanation
of howyoucanusethissystemcallrepeatedly
to obtain
theentirepathnamefor a file,seethedescription
of thissystemcallin theExtendert
|RMX II BasícI/O SystemCallsReference
Manual.

3.6.10 ManipulatingExtensionData
When you format a volumeto accommodatenamedîiles,you havethe option of allowing
eachfìle to includeextensiondata. The Basicl/O Systemprovidestwo systemcalÌsthat
albw you to get and set extensiondata. Thesecallsapplyto both data and directoryfiles.
. A$SET$EXTENSIoN$DATA
This call providesa meansofwrjring extensiondata. A$SET$EXTENSION$DATA
can be usedeven if the file connectionis not open.
.

A$GET$EXTENSION$DATA
This callprovidesa meansof readingexrensiondata. A$GET$EXTENSTON$DATA
c;ln be usedevenifthe file connectionis not open.

3.6.11Detecting
Changesin DeviceStatus
TheBasicI/O SystemprovidestheA$SPECIALsysrem
callro allowyourappÌication
to
detecta changein thestarusofthe devicecontaining
yournamedfile tree. Specifically,
yourapplication
canusethe"notify"lunctionof theA$SPECLAL
systemcallto establish
a
mechanism
tbr findingout if thedeviceceases
to be ready.For moreiaformation,
reier
to dìe A$SPECIAL secrior o'l fheEnended|RVIXII BasicI/O SJstefiCatL,Refercne
tr[anual.

3-18

Basicl/O Us€r'sCuide

NAMED FILES

3.7 ACCESSING
THEGLOBALTIME.OF-DAY
CLOCK
The BasicI/O Systemprovidesone systemcall that obtainsthe rime of day from a
battery-poweredtime-of-dayclocl, (calleda globalclock),if sucha clock is available.
Another systemcall existsto set the globaltime-of-dayckrk. The systemcallsare
.

GET$GLoBAL$TIME
This systemcall retu.ns the date and time valuestoredin the globaltime-of-day
systemclock.

SET$GLoBAr-$TIME
This call setsthe globaldate and timEvaluesin the gÌ!ìballime-of-Llayclock.

3.8 ACCESSING
FILESTHROUGH
iRMX-NET
The BasicI/O Systemsupports
the iRMX NET localareanetworkstandardby allowing
youto configurethe remotefile driverandbyprovidingtheENCRYPI systemcall. This
systemcallencrypts
passwords
asdefinedby theìRMX-NETlocalareanetwork
encry?tion
standard.

3.9 CHRONOLOGICAL
OVERVIEW
OF NAMEDFILES
Thesystemcallsthatcanbeusedwith namedfilescannotbe usedin arbitraryorder. This
sectionprovidesyouwith a senseof howthecallsrelateto oneanother.

3.9.1MostFrequently
UsedSystemCalls
Figure 3-3 showsthe chronologicalreÌltionshipsbetweenthe most frequentlyusedBasic
l/O Systemcalls. To usethe figure,startwith the leftmostbox and follow the arrows.
Any path that you can trace is a legitimatesequenceof systemcalls. Keep in mind that
this figure doesnot representall possiblesequences.

3.9.2CallsRelating
to UserObjects
The systemcallsrelatingto userobjectsare completelyindependentoi other BasicI/O
SystemcalÌs. With one exception,your applicationmust havea userobjectbefore it can
trseany systemcall requiringa userobject.
Five systeú callsp€rtain to userobjects.Ofthe five, GET$DEFAULT$USER and
CREATE$USER can be invokedat any time. Two others,DELETE$USER and
INSPECT$USER,can be invokedonly after userobjectsexist. The remainingcall,
SET$DEFAULT$USER requiresthat both ajoh and a userohjectexist.

BasicI/O User's cuide

3-.19

NAMEDFILES

f ' "l

'l.l[i+l[]f;

- r^"ri:" { - l ' L. i l L
f'

DATA FILES

DIRECÎORIES

-f___l

l- 'l

[-l [J

.4r

l'l

| {_ti_l l

!ró+ I

.]-.r
l'.'""1

.-l

Drr r

Ioturr

L----r _-1,

figure 3-3, Chronolos/ of FrequentlyUsedSystemCalls for Named[iles

3.9.3 CallsRelatingto Prefixes
The GET$DHFAULT$PREFIX systemcall can be invokedwhenevera job exists.The
SÉ f$ DEFAULT$PREFIX.however.
rcquireshorha job and c uscrohject.

3.9.4CallsRelating
to Status
Bothof the status-related
systemcalls,A$GET$FILE$STATUS
and
A$GET$CONNECTION$STATUS,
canbe invokedwhenever
yourapplìcation
hasa file
connection.

3.9.5CallsRelating
to ChangingAccess
The only systemcall relatedto changingaccess,
A$CILANGE$ACCESS,can be invoked
whoneveryour applicationhasboth a userobj€cland a path or conneclionto a file.

-ì.:0

BasicI/O User'sGuid€

NAMEDFILES

3.9.6Callsfor Monitoring
DeviceBeadiness
There is only one syst€nìcaLltlìat letsyour applicationmonitor the readinessof a device,
the A$SPECIAL systemcall. Your applicationcan usethe "notiry"function of this call
any time after your applicationhasobtaineda dcviccconncction.

3,9.7 CallsRelatingto ExtensionData
The two systemcallsrelatingto extensiondata,A$GET$EXTENSION$DATA and
A$SET$EXTENSION$DATA,can be invokedwheneveryour applicationhasa
connectionto a file-

3.9.8 Calls for RenamingFiles
The one call for renaminga file, A$RENAME$FILE, can be usedwheneveryour
applicationhasa connectionto the file to b€ renam€d,a userobject,and a path that is to
becomethe newpathname.

3.9.9 Calls for ldentifyingFile Names
There is only one systemcall for finding out a file's name,
A$GET$PATH$COMPONENT. Your applìcationcan usethis callwheneverthe
applicationhas a connectionto the file.

3 . 9 . 1 0 C a l l sf o r | R M X - N E T
The BIOS systemcall ENCRYPT encryptsa passwordto enableremote file ac4ess
throughiRMX NET. You must use this call to encrypta password.The ENCRYPT
systemcall can alsobe usedby any applicationthat needsto perform password
encryption. Passworddecryptionis not supported.

Rasic I/O flsefs Gùide

3-21

CHAPTER
4

PHYSICALFILES

4.1 INTRODUCTION
TheBasicI/O System
providesphysicalfilesto allowyourapplications
to .ead(or write)
stringsof bltes from (or îo) a device.Aphysicallile occupies
an entiredevice,andthe
BasicI/O System
providesyourapplications
wjth the abilityto capitalizeon the physical
characteristics
of thedevice-

4.2 SITUATIONS
REQUIRING
PHYSICAL
FILES
The closerelationshipbetweena deviceand a physicalfile is particularlyusefulwhenyour
applicationusessequentialdevices.For example,you shouldusephysicalfiles to
communicatewith line printers,djsplaytubes,plotters,magnetictape unirs,and robots.
There are evensomeinsÌanceswhereyou shouldusephysicalfiÌes to communicatewith
random devicessuchas disks,diskettes,ànd bubblememories. For instance
.

FormattingVolumes
Wheneveryou createan applicationto format a disk or diskette,the appÌicationmust
haveaccessto everybyteon the volume. Only physicalfiles provide this kind of
access.

Volumesin FormatsRequiredby Other Systems
llyour applicationmust read or write volumesthat havebeenformatÌedlor systems
other than the BasicI/O System,you must usephysicalfiles. Your applicarionwill
haveto interpret suchinformalion as lobelsand file structures.A physicalfile can
provideyour applicationwith accessto the raw information.

Implementing
Your Own File Format
Supposethat your applicationrequiresa ìesssofhisticaîedfile strùctùrethan thxt
provicJed
by iRMX Il namedfiles. You can build a customfile structureusjnga
Dhvsicalfile as a lbundation.

BasicI/O User's Guide

,l-l

PIIYSICAL
FILES

4.3 CONNECTIONS
ANDPHYSICAL
FILES
Although there js a one{o-one correspondence
betweenthe byteson a deviceand the
bytesof a physicalfile, the deviceconnectionis different than the file connection.The
BasicI/O Systemmaintainsthis distinctionto remainconsistentwith namedfiles and
slreamfiles. This consistenryhelpsyou developapplic,ltionsthat can useany kind offile.

4.4 USINGPHYSICAL
FILES
Severalsystemcallscan be usedwith physicalliles, but the order in which they are usedis
not arbitrary. The followinglist providesa brief description(in chronologicalorder) of
*,hat an applicatìonmust do to usea physicalfile.
1.

Obtain a deviceconnection.
Your applicationmust call A$PHYSICAL$ATTACH$DEVICE to obtain a device
connectionîor the device. This needst() be rloneonly oncefor eachdeJr'ice
and is
necessaryfor t\r'oreasons.When your applicationcreatesthe physicalfile. the
deviceconnectiontells the BasicI/O Systemwhich deviceis to containthe file and
alsothat the file must be a physicalfile.

Obtain a file connection
lfyour applicationknowsthat the file hasnor yet beencreated,it shouldusethe
A$CREATE$FILE syst€nìcall to ot,tdina {ile connecrion.This witt work evenif rhe
physicalîile hasalreadybeencreirted. Use the token of the deviceconnectionas the
PREFIX parameterto tell the BasicI/O Systemwhich deviceyou want asyour
physicaJfile.
If, on the other hand,your applicarionis certainthat the file hasalreadybeen
created,usethe A$ATTACH$FILE systemcall to obtain the file connection.To do
this, your applicationcan us€either the deviceconnectionfor th€ deviceor an
existjngfile connectionto the file as the PREFIX parameterin the systemcall.
This carefuldistinctionbetweenthe AXiCREATE$FILEand the
A$ATTACH$FILE systemcallsis necessarv
ro be consistentwith namedfiles. If
you want your applicationro work with any kind of file, vou must maintainthis
consistency.

Open the file connection.
Use the A$OPEN systemcall to open the connection.When openingthe
connection,your applicationmust specilJ,how thc file can be sharedand how the
aDolicationusesthe conne,ction.

BasicI/O SystemUse.'sGuide

PHYSICALFILES

Manipulatethe file.
Four systemcallscan be usedto read,wite, or otherwisemanipulateyour physical
file:

The A$READ and A$WRITE systemcallscan be usedto read from tlìe device
and write to the device,respectively.

The A$SEEK systemcall can be usedto manipulatethe file conne.tion'sfile
pointer if the deviceis a randomdevicesuchas disk,diskette,or bubble.

The A$SPECIAL systemcall can be usedto requestdevice-dependenî
functions
from the devicedriver. The precisenature of thesefunctionsdependsupon the
kind of deviceand the numberof specialfunctionssupportedby the device
driver. Be awarethat useof specialfunctionscan preventan applicationfrom
being device-independent.
Closethe file connection.

Use the A$CLOSE systemcali to closethe connecîion.This is particularly
important if the sharemode of the connectionrestrictsrhe use of rhe fite through
other connections.Note that your applicttion can repeatsteps2, 3, and 4 any
numberof times.
6.

Delete the file conneltion,
Use the A$DELETE$CONNECIION systemcall to deleterhe file connection.
This is only necessaryifyour applicationis complet€lylinishedusingthe file.

Requestthat the devicebe detached.
Invoke the A$PHYSICAI$DETACH$DEVICE sysremcall to l€t the Operating
Systemknow whenyour applicatìonis finishedusingthe device. The Operating
Systemkeepstrack ofthe numberof applicationsusingthe deviceand avoids
detachingit until it is no longerbeingusedby any applicaîion.Only then doesthe
OperatingSystemactuallydetachthe device.

All of these systemcalls are described in the Extmded íRMX II Basic I/O SystemCalb
ReferenceManual.

BasicI/O User's Cuide

4-3

5.1 INTRODUCTION
Streamfiles provide a meansfor one taskto sendlarge amountsof informationto
anothertask. Be awareîhat this is one of severaltechniquesforjob{o-job
communication.If you are not familiar with other techniques,refer to fhe E).fenled
.RMX II ProgrammingTechniquesManual.
The aspectof streamfiles that makesthem very usefulis that lhey allow a task to
communicatewith a secondtask as thoughthe secondtaskwere a device. This extends
the notion of deviceindependence
to includetasks.
Becausetwo tasksare involvedin usingeachstreamfile, eachtask must perform one half
of a protocol. There are severalprotocolsthat work, but the followingone is typicaland
seÍvesas a good illustration. Note that the two halvesofthe protocolcan be performedin
either order or concurrently.

5.2 ACTIONSREQUIRED
OF THEWRITINGTASK
The writing task must perform sevenstepsin its halfofthe protocol to ensurethat it has
established
communication
with the readingtask The stepsare
l.

Obtain a connectionto the streamlile device.
Although streamiiles do not actuallyrequie a physicaldevice,your applicationmtrst
ca A$PHYSICAL$ATTACH$DEVICE to obtain a deviceconnectionb€ror€
creatinga streamtile. This is necessary
because,
when your applicationinvokesthe
A$CREATE$FILE systemcall, the deviceconnectiontells the BasicI/O System
what kind of file to creare.
The A$PHYSICAL$ATTACH$DEVICE systemcall requiresa pa.ameterthat
identifiesthe deviceto be attached.For streamfiles,there is only one device,and its
nameis specifiedduringthe processof configuringthe system.lntel recommends
the name"STREAM", but iî is possiblethat the personresponsibletbr contigùring
your systemchangedthis name. For the remainderof this discussion,this manual
assuuì€slhat lhe nilrneofyour slslem'srtream file deviceis "STREAM".

BasicI/O Useis Guide

5-1

STREAM F'II,ES

As with other devices,"STREAM" cannotbe multiply attached,so the system
programshouldbe written so as to callA$PHYSICAL$ATIACH$DEVICE or y
once. The programcan then savethe deviceconnecîionand passit to any
applicatjonprogramthat requestsit.

Createthe streamfile.
Use the A$CREATE$FILE systemcall with the deviceconnectionto createthe
streamfile and obtaina token for a file connectionto the streamfìle. Use the token
for the deviceconnectionas the PREFIX parameter,in order to tell the BasicI/O
Systemto createa streamfile.

Passthe file connectionto the readingtask.
'Ìhere
are severalwaysof doingthis, includingthe Ìrseof objectdirectoriesand
mailboxes.For e{licit instructions,refer to the Er.tended
iRMX II prcyamhíng
TechniquesManual.

Open the file for writìng.
Use the A$OPEN systemcall to open the file conne,ction
for writing. Set the
CONNECTION parameterequalto the token for the fiìe connection;set the MODE
parameterfor writing: and set the SHARE parameterfor sharingonly with readers.

Write informationto the strcamfiìc.
Use the A$WzuTE systemcall as often as neededto write informationto the stream
file. Use the îoken for the file connectionas the CONNECTION parameter.
The BasicI/O Systemusesthe concurrenrpart of the AgWzuTE systemcall to
synchronizethe writing and readingtaskson a call-by-caìÌ
basìs.The BasicI/O
Systemdoesthis by sendinga responseto eachinvocationof ASWRITE only after
the readingtaskhasfinishedreadingall informationthar waswritten by the
A$WRITE call.
Closethe connection.
When finishedwriting to the streamfile, usethe A$CLOSE systcmcall to closethe
connection.Note that after this step,the writing taskcan repeatsteps4, 5, and 6 as
manytimesasneeded.
Delete the connection.
Use the A$DELETE$CONNECIION sysremcall to deletethe connecrionto the
streamfile.

All of thesesystemcallsare describedin the Ettended.
íRIIX II BasicI/O Sy:temCath
RekrenceManual.

BasicI/O Usedscuide

STRXAMFILES

5.3 ACTIONSREQUIRED
OF THEREADING
TASK
The readingtask must perform the followingsiy stepsin its half of the protocolto
successfully
read the informationwritten by the writing task.
1.

Cet the file connecrioofor the streamfile.s-:
The techniqueusedto accompiishthis dependson how the writing taskpassedthe
file connection.

Createa secondfile connectionfor the streamfile.
The.e are two reasonsfor doingthis. First, the readingtask must havea dilferent
file pointer thar that of th€ \yriti,ìgtask. Second,tle BasicI/O Systemrcjeclsany
connecîionscreatedin one.jobbut usedby anoth€rto manipulatea file.
Obtain this new connectionby usingthe A$ATTACH$FILE systemcall. Set the
PREFIX parameterto the token for the originalfile connection.

NOTE
The readingtask can alsousethe A$CREATE$FILE systemcall to obtain
the new connectionto the samestreamfile. The reasonfor this is that the
BasicI/O Systemexaminesthe natur€ofthe PREFIX parameterin the
A$CREATE$FILE systemcall. If the valueprovidedis a device
corinection,the BasicI/O Systernwill creotea new file and return a
connectionfor it. On tlìe other hand,il the valLreprovidedis d file
connection,the BasicI/O Systemwill just cteateanotherconnectionto the
samefile.
This carefuldistinctionbetw€enthe A$CREATE$FILE and the
A$ATTACH$FILE systemcallsis necessaryto be consistentwith named
and physicalfiles. If you wantyour applicationto work with any kind of
file, you must maintainlhis consìslency.
3.

Open the new file connectionfor reading.
Use the A$OPEN systemcall to open the connectionfor reading. Setthe
CONNECTION parameterequalto the bken for the new connection.Set the
MODE parameterfor reading,and set the SHARE parameterfor sharingwith all
connectionsto the file-

Commencereading.
Use the A$RBAD systemcall to reiìd the lile until readingis no longernecessaryor
until an end-of-fileconditionis detectedbv the BasicI/O Svstem.

Closethe new file connection.
Use the A$CLOSE systemcall to closethe new file connection.Note that after this
step,the readingtaskcan repeatsteps3, 4, and 5 as manytimes as needed.

BasicI/O Use/s Guide

S'TR,EAM
FILES

Delete the new lile connection.
Use the A$DELETE$CONNECTTONsystemcallto deletethe new connechonto
the streamfile. The writing task deletesthe old connection,and,as soonas both
connectionshavebeendeleted,the BasicI/O Systemdeletesthe streamfile.

All of these systemcafs are descrìbedìn the Extetule.l|RMX Il BasícI/O SystemColb
ReferenaeManwl.

5-,1

BasicI/O Uset'scuide

5.1 INTRODUCTION
This chapterprovidesyou with backgound informationon the systemcallsof the Basic
I/O System.For detailedinformationon systemcall par arîe|ers,refeî 6 theE$ended
iRMX II Basic I/O Systen Calb ReferenceManual.
BIOS syst.em
callscan be dividedinto two caÌegoriesaccordingto their names. The first
categoryconsistsofsystemcallshavingnamesof the form
RQ$XXXXX
whereXXXXX is a brief descriptionof what the systemcall does. The secondcategory
consistsof systemcallshavingnnmesof the form
RQ$A$XXXXX
Systemcallsof the first category,without the A, are synchronous
calls. They begin
runnìngas soonas your applicationinvokesthem,and continuerunninguntil they detect
an error or accomplisheveq4hingtheymust do. Then they return control to your
application. In other words.synchronous
callsact like srrbroutines.
Systemci ls of the secondcategory(thosewith the A) are calledasynchronous
because
they accomplishtheir objectivesby usingtasksthat run concurrentlywith your appÌication.
This allowsyour applicationto accomplishsomework while the BasicI/O Systemdeals
with devicessuchas disk drivesand tape drives.

6.2 SYNCHRONOUS
SYSTEMCALLS
Thefollowingparagraphs
explainpropertiesofcertaininputparameters
to synchronous
BasicI/O System
calls.

BasicI/O User'sCùid€

6.1

SY\CHRONOUS
ANDASINCHRONOUS
SYSTEMCALLS

6.2.1UserParameter
This parameteris specifiedin manysynchronous
systemcalls(and il someasynchronous
onesaswell). It containsa token designatingthe caller'suscr objcc!. A
SELECTOR$OF(NIL) specificationdesignates
the defaultuser. The BasicI/O System
ignoresthis parameterfor physicÀland streamfiles.

6.2.2 File-PathParameter(s)
for NamedFiles
Namedfiles are designatedin systemcallsby specifyingtheir path, that is, thei prefix and
subpath.The prefi\ pa.ametercan be a token designatingan existingdeviceconne.tion
or file connection.lf this parameteris SELECTOR$OF(ML), the defaultprefix for the
callingtask'sjob is assumed.
For namedfiles, the subpathparameteris a pointer to an ASCII string. The form ofthis
string is describedin the followingparagraph.The subpathcan also be NIL or can point
to a null string,in which casea prefix indicaresrhe desiredconnection.For physicaland
streamfiles, the subpathparameteris alwaysignored.

NOTE
A file connectionthat wasobtainedin onejob cannotbe usedas a
connectionby anotherjob- However,a file connectioncan be usedas a
prefix by otherjobs in any call requiringprelix and subpathparameters.
(The only exceptionsto this rule are that rhe otherjobs cannoruse rhe
connectionas a prefix while specilyinga null subpathin callsto
A$CHANGE$ACCESSor A$DELETE$FILE.) This meansthat a file
connectioncan be passedto anotherjob and the otherjob can obtain its
own connectionto the samefile by callingA$AT-|'ACH$FILE,with the
passedfile connectionbeingusedas the prefix paramet€rin the call.

6"2

Basicl/O User'scuide

SYNCHRONOUSAND ASYNCHRONOUSSYSTEMCALLS

Systemc{lls rcfcrring to namedfiles can specifypatlrsin the followilg forms:
Prefix

Subpath

DesìgnatedConnection

a pomter
to a null string

Connectionwhosetoken
is the deiault prefix.

Pointerto
ASCII string

ASCII string definesa
path from the connection
whosetokenis the
delàult prefix to the
targetconnection-

token

a pcinter
to a null string

Connectionwhosetoken
is containedin the preîix.

token

Pointerto
ASCII string

Prefixparxmeter
containsa token for a
connection.ASCII string
deîinesa path from thît
conneclionto the target
connection.

The subparhASCII stringis a lisr of file namesseperatedby slashes,terminatingwith the
desiredfile. A file namecan be 1-14ASCII characters,includingany printîble ASCII
characterexceptthe slash(/) and up-arrow0 or circumflex("). In Figure 6-1,for
example,if the preîix is the token for directoryOBSTETRICSand we wìshto reference
lile OUT-PATIENT, the subpathparamerermust point to the srrjng
DELIVERY/POST-PARTUM/OUT.PATIENT
If the ASCII stringbeginswith a slash,the prefir mcrcly dcsignatcsthe tree and thc
subpathis assumedto start at the root directoryof the tree associated
with the prefix.
For example,if the prefix designares
directoryGYNECOLOGY in Figure6-t, the
subparhro oUT-PATIENT is
/OBSTETRICS/DELIVERY/POST.PARTUM/OUT-PATIENT
Namedfiles can alsobe addressedrelativeto other files in the tr€e, using',î',or ,'/,'as a
patfì component. (Thesetwo symbolshavethe samemeaning. Scmeterminalsdo not
havethe up-arrowkey.) The " t " of "/" ref€rslo the p{renr direcroryof the currenrfile in
the path scan. For example,now rhat we havea connecrionto OUT-PATIENT in Figure
6-1,we can usethal connectionto specirya subparhto IN PATIEìVT. With thc rokcn for
the OUT-PATIENT connectionas our prefix, the subpathsrringwould be
/IN-PATIENT

BasicI/O Usefscuide

SYNCHRONOUSAND ASYNCHRONOUSSYSTEMCAI,I,S

Notethatno slashfollowsthe "/" in thisexample.
Of coursean evensimplerapproach
wouldbe to designate
diectorypOST-pARTUMas
theprefix,in whichcasetheASCIIstringbecomes
lN.PATIENT

NOTE
The Basic I/O System does not distinguish bet\"reenuppcrcase and

lowercase
characters
in subpaths.For example,
thesubpath,,xlz,,is
equivalent
to thesubpath"XYZ".

6.2.3 ResponseMailboxParameter
This parameteris specifiedonly in asynchronous
systemcalls. It containsa token
designatingthe mailboxthar is ro receivethe result of the call. This informations
providedby tasksto synchronìzeparalleloperations.To receivethe result of the call,a
task must either call RECEIVE$MESSAGEand wait at the desisnatedmailboxor call
Vr'AIT$IO. Be awarethat if seveÍalcills sharerhe rÀmemailhoxlthe resuLtsmav be
receivedout of orderMost asynchfoloussystemcallsreturn only an I/O resultsegmentto the response
mailbox. This segmentcontainsan exceptioncodeand other intbrmationaboutthe
operation. AppendixC describesthe I/O rcsulrsegment.Other systenìcallsA$ATTACH$FILE, A$CREATE$DIRECTORY, A$CREATE$FILE, ANd
A$PHYSTCAI.$ATTACH$DEVICE-return to the mailboxa token for a connecrionif
the systemcallperformssuccessfully
or an I/O resultsegmentotherwise.After calling
RECEIVE$MESSAGEto obtain the result of one of thesesystemcalls,a task should
perform a GET$TYPE systemcall to ascertainthe type of objectfeturned to the response
mailbox. The ertended .RMX II NucteusUse,"îGu,dedescribesGET$TI?E in

lf SystemInitializationError Reportingis not corifiguredinto the system,the original
BIOS initiali2ationtaskplacesthe BIOS ID code(2) and the correspondingcrror codc
irto the first two words of the Nucleusdata segment(1E0t0000H).If no monitor is
configured,it then goesinto an infinite error loop.

7.10 FACTORS
AFFECTING
BASICI/O SYSTEMPERFORMANCE
The purposeof this sectionis to makeyou awareof the factorsthat havethe greatest
impacton the performance(speed)of rhe BasicI/O Sysrem.Note that you determine
somcof thesefactorsduring softwareconfiguratior,bu! you determineother factorsat
other times. The factorsare as follows:
.

Devicegranularity,which is the smallestnumberof bytesthat can be read from or
written to a devicein a singleI/O operation. Ifthis valueis selectable,
you determine
it either byjumperìnghardwareor by meansof software,dependingupon the device.

Volume granularity,whichis the smallestnumberof contiguousby'testhat can be
allocatedfrom a volumein a singleallocation.This valuecanvary from volume to
volume and must be a multiple of the devicegranularity. You specifyit wtren
formattingthe volumewith the FORMAT commandof the Human lntefiace.

File granularity,which is the smallestnumberof bytesthat can be allocntedto a file ifl
a singleallocation.This valuecan vary from file to file and must be a multiple of rhe
volumegranularity. You specifyeachfile's granularitywhen creatingthe file with the
A$CREATE$FILE systemcall.

The numberof buffersfor eachdevice-unit.You sperily thisvaluewhenconfiguring
the BasicI/O System.

The numberof bytesto be read or written. You specilythis value in callsro ASREAD
and A$WRITE.

The amountof time betweenupdatesperfbrmedby the fixed updateand timeout
updale features-You specifythesetime intewalswhen configuringthe BasicI/O
Systern.îìesc lwo kinds of updatingare explairledin the E tended.RMX II BasícI/o
SystemCalk Reference
Marual in the descriptionofthe A$UPDATE systemcall.

For bestresultswith thesefactors,you shouldbeginby usingyour bestjudgment, Then,
usingthe resultingperformancefiguresas a base.you can experimentby changinga few
(perhapsonly one) factorsat a tìme.
Obtainingthe optimum combinationof thesefactorsis vital to the p€rformanceof any
applicationof which I/O operationsare a major part. Testingsystemperformancewith
variouscombinationscan resultin a systemwith higherperlormance.

Basic l/O User's cuide

|BMX@ll

4.1 DATATYPES
The followingare the data typesrhat are recogìizedby the iRMX ÌI OperatingSysrem:
BOOLEAN

A BYTE that is consideredto havea valueof TRUE if it is (}FFH,and
FAIJE if ir is 00H. In PL/M-286,
DECIARE BOOLEAN LITERALLY 'BYTE';

BYTE

An unsignedeight-bitbinarynumber.

DWORD

An unsignedfour-bytebinary number.

INTEGER

A signedtwo-bytebinàrynumberthat is storedin two,scomplementform.

OFFSET

A WORD whosevaÌuerepresentsthe distancefrom the baseof an 80286
segment.

POINTER

Two consecutiveWORDs containingthe selectorof an 80286segmentand
an offsetinto that segùent. The offsetmust be in the word havingthe
lower address.

SELECTOR An index into a dercriptortablethat identifiesa partic:ularmerrrory
-l
segment. he descriptortable entry lists the segment,sbase,limit, qpe,
and privilegelevel.
STRING

A sequenceofconsecutiveBYTES. The valuecontainedil the first byte is
the numberol bj,testhat follow it in the string.

TOKEN

A SELECIOR that containsthe logicaladdressof an object. The selector
rcfcrs ro an entry in rhe descrjprortablethar lisrsrhe physicaladdressof
the ob.ject.A token must be declaredliterally a SELECTOR.

WORD

An unsìgnedtwo-bytebinarynumber.

BasicI/O Usefs cuide

A"t

8.1 INTRODUCTION
Thisappendirliststhe Rpecodesfor all iRMX II objects.In addition,it rJocuments
the
amountof memoryneededto createBasicI/O Systemobjects.

8.2 OBJECTTYPES
Each iRMX Il objecttype is knownwithin iRMX II systemsby meansof a numericcodeTableB-l liststhe tyDeswith their codes.

TableB-1. TypeCodes
OEJECT
TYPE
Task

RegÌon
Segment
Extension
Cornposile

l/O Job
Log calDevice
User Crealed
Composlie

NUMERICCODE
1
2
3
5
6
7
I
100
101
300
301
varièslrom 80O0Hto
oFFFFHdepencling
on thevalu6
specified
in CREATE$EXTENSION

lhe firsr€ ght oqeds. plùsLse.creareo
composites,
aredesc'oed ltte ExtendediRMX II
Nucleus Uter't Cuidc Use.a'ìdcoîr edior oo €cÚypesaredesc oedin Claprer4 oflîis
manual. l/O jobs and log cal d€vicesare describedin rheExtended ìRMX II Extended I/O
S\\km U:cr'r Gt'ide.

BasicI/O Usefs Cuide

B-1

OtsJECT
TYPESA\D RESOURCE
R-EQUIREMENTS

8.3 RESOURCE
REQUIREMENTS
TheBasicI/O Systemobtainsmemoryîrom thecallingjob'smemorypoolwhencreating
objects. The values listed here reflect Release3 of the iRMX II Operating System.

Object

paragraphs
Numberof 16-b)1e
requiredby theBasicI/O System

I/O Result
Segment

4 (5 for an internalIORSthat theOperating
System
createswhenattachinga device)

Connection
(to

namedfile)

B-2

Connectìon(to
physicalfile)

User object

3 (rrinimum)

BasicI/O Usefs Guide

c.1 ovERvtEw
Cerîainasynchronous
I/O systemcallsreturna datastructurecalledan I/O Result
Segment
to themailboxspecified
by the"resp$mbox"
parameter.The followingsystem
callscanretuansucha segment:
A$ATTACH$FILE
A$CIIANCE$ACCESS
A$CLOSE
A$CREATE$DIRECTORY
A$CREATE$FILE
A$DELETE$CONNECTION
A$DELETE$FILE
A$OPEN
A$PHYSICAL$AT-IACH$DEVICE
A$PHYSICAI$DETACH$DEVICE
A$READ
A$RENAME$FILE
A$SEEK
A$SPECIAL
A$TRUNCATE
A$UPDATE
A$WzuTE
Fourof thesesystemcals (A$ATTACH$FILE,
A$CREATE$DIRECTORY,
A$CREATE$FILE,andA$PHYSICAI$ATTACH$DEVICE)
canreturneithera
connection
or an I/O resultsegrnent
to the mailbox.Your application
taskcandetermine
whichrypeof objecthasbeenreturnedby makinga GET$TYPEsystemcallbeforetrying
to examinethe object.
Beforewaitingat the response
mailboxto receivetheI/O resultsegment,
yourapplication
task should examine the condition code returned in the word poiltEd to by the

parameter.If thiscodeis "E$OK",the taskcanwaitat the mailbox.
"except$ptr"
However,if thecodeis not 'rE$OKr',
an exceptional
conditionexistsandnothingis sentto
themailbox.

BàsicI/O Use s Cuide

c-1

I/O RESULTSECMENT

lmmediatelyafter receivingthe I/O result segm€nt,the task shouldexaminethe status
field. This field containsan "E$OK" if the systemcall wascompletedsuccessfully
or an
exceptional-condition
codeif an error occurred.The result segnent alsocontainsthe
actualnumbcr oI bytesread or wtitten, if appropriate.

c.2 STRUCTURE
OFt/O RESULTSEGMENT
TheI/O resultsegment
is structu.edasfollowsl
DECIÀRE
statìrs

iors

STRUCTURE(
UORD,

unirgsrarus
a cr u a l

WORD,
WORD./;

where
status

Conditioncode indicatingthe outcomeof the call. AppendixD lists these
asynchronous
conditioncodes.

unit$status

The lower four bits oî this fietd containdevice-dependent
error code
information that is meaninglulonly if the statusis E$IO. The codes,their
meanings.and their associated
mnemonicsare as foììows:
Code Mnemonic

Meaning

IO$UNCI-ASS

An error occurredfor which
it wasimpossibl€to ascertain
the cause.

IO$SOF|

Softerror;theI/O sysrem
hasretriedtheoperationand
failed;another.etryis Íot
possible.

IO$HARD

Hard error;a retryis not
possibÌe.

IO$OPRINT

Operaro. intervention is

required.
4

IO$WRPROT

lvrite-prorected
volume.

IO$NO$DATA

No daraon the nextrape
record,

BasicI/O Usels Guide

I/O RESULTSEGMENT

Code Mnemonic

actual

Meaning

IO$MODE

A read (or write) was
attemptedbeiore the
prcviouswrite (or read)
completed.

IO$NO$SPARES

An I/O error occurred
during disk formatting;no
alternatetrackswere
available.

IO$AIT$ASSIGNED

An l/O error ou:urred
during disk formatring;an
alteanatetrack wasassigned.

The actualnumberof bytestransferred.

The I/O result segmentconlainsother fieldswhichare of interestonty to the designerof
a device driver. Relel. ro fhe Extenrled\RMX lI DeviceDrivers Ltset'sGuide for
ìnformationaboutthc rcmainingfields in the I/O rcsult seglìl€Dt.

C.3 UNITSTATUSFORSPECIFICDEVICES
You may needto know the informarioncontainedin the',unitgstatus,'field
for the
foÌlowing devices.

C.3.1|SBC@
214/215cControiler
Undercertaincircumstances,
the iSBC215Winchester
diskcontrollerandthe iSBC214
diskette,disk,andtapecontrollerplaceinformationin the hightwelvebitsof thisword. If
thelowfour bitsindicateIO$SOFI,rhecontrollersetsthe highrwelvebitsasfollows:
Bit

Interpretation

15(leftmost)
14
13
12
11
10-8
I
6-4

I =seekerror
1=cylinderaddress
miscompare
l=drivefault
l=lD fieldECCerror
l=datafieldECCerror
unused
| =sectornot found
unused

Basict/O Usefs cuide

c-3

r/O RNSULTSEGMENT

On theotherhand,if thelow four bitsindicateIO$HARD,rheiSBC215c andiSBC214
controllers
setthe hish 12bitsasfollows:

Bir

Inter?retation

I =invalid address
1=sectornot fbund
I = invalid command
1= no index
1=diagnosticfault
1= illegalsectorsize
1= end ofmedia
I = illegalformat qpe
1= seekin progress

1= ROM effot

1= RAM error
unused

15
14
13

12
1l
10
ó

Ifyou needmore detailedinformationregardingthe meaningof theseerrors,refer to the
iSBCols WîhchesterDisk Cotttroller HardwareReferenceManuel ot to the iSBC@2j4MuttiPeipheml CotrtrollerHctrdwarcReferenceManual.

C-,1

BasicI/O Usefs Guide

D.f OVERVIEW
Thisappendixliststwotlpesof €xception
codes,Thosedetectedsynchronously
with
systemcallinvocation
(sequential
codes)andthosedetectedduringthe asynchronous
portionof systemcallprocessing
(concurrent
codes).Exception
conditjons
arefurther
classified
into programmer
errorsandenvironm€ntal
conditions.A programmer
erroris
a conditionthatis preventable
bythecallingtask.An environmental
conditionrsan
exc€ption
conditioncaused
bycircumstances
beyondthecontrolof thecalingtask. The
sequential
codesarereturnedto rhelocatìonaddressed
by the ',except$ptr"
field ofthe
system call. The concurrent codes are returncd in an I/O result segment (see Appendix
C). This appendix Jìstsall codes with their decimal and hexadecirnalequivalents.

D.2 SEQUENTIAL
(ENVIRONMENTAL)
EXCEPTION
CODES
CODE
E$OK
E$TIME
E$MEM
E$I,IMIT
E$EXIST
E$NOT$CONFIGURED
E$SUPPORT
E$DEV$OFF$LINE
E$IFDR
E$NOT$FILE$CONN
E$NOT$DEvICE$CONN
E$BUFFERED$CONN
E$NOT$SAME$DEVICE
E$PATHNAME$SYNTAX

BasicI/O Uset's Guide

DECIMAL

i
2
4
6
8
46
47

50
51
58
62

HEXADECIMAL
OH
lII

2H
4H
6H
8H
23H
2EH
2FH
32H
33H
36H
3AH
3EH

D-l

EXCEPTIONCODES

D.3 SEQUENTTAL
(PROGRAMMER
ERROR)EXCEPT|ON
CODES
CODE

DECiMAL

IIEXADECIMAL

E$TYPE
E$PARAM
E$NOUSER
E$NOPREFIX
E$BAD$BUFF

32770
32'772
32801
32802
32803

8002H
8004H
8021H
8022H
8023H

D.4 CONCURRENT
(ENVTRONMENTAL)
EXCEPT|ON
CODES

D-2

CODE

DECIMAL

HEXADECIMAL

E$OK
E$MEM
E$FEXIST
E$FNEXIST
E$DEVFD
E$SUPPORT
E$EMPTY$ENTRY
E$DIR$END
E$FACCESS
E$FTYPE
E$SHARE
E$SPACE
E$IDDR
E$to
E$FLUSHING
E$ILLVOL
E$DEV$OFFLINE
E$IFDR
E$FRAGMENTATION
E$DIR$NOT$trMPTY
E$NOT$FILE$CONN
E$NOT$DEVICE$CONN
E$CONN$NOT$OPEN
E$CONN$OPEN
E$BUFFERED$CONN
E$OUTSTANDING$CONNS
E$AIREADY$ATTACHED
E$DEV$DETACHINO
E$NOT$SAME$DEVICE
E$ILLOGICAL$RENAME

0
2
32
33
31
35
36
37
38
39
40
41
42

OH
2H
20H
21H
22H
23H
24H
25H
26H
27H

,+3
41
45
4ó
47
48
49
50
51

52
53
55
56
5'7
58
59

28H

29H
2AH
2BH
2CH
2DH
2EH
2FH
30H
31H
32H
33H
34H
35H
36H
37H
3IJH
39H
3AH
]BH

BasicI/O User'sGuide

EXCEPTIONCODES

CODE

DECIMAL

HEXADECIMAL

E$STREAM$SPECIAL
E$INVALID$FNODE
E$P THNAME$SYNTAX
E$FNODE$LIMIT
E$IO$IINCLASS
E$IO$SOFT
E$IO$HARD
E$IO$OPRINT
E$IO$WRPROT
E$IO$NO$DATA
E$IO$MODE
E$IO$NO$SPARES
E$IO$ATT$ASSIGNED

ó0

3CH
3DH
3EH
3FH
50H
5lH
52H
53H
54H
55H
5óH
57H
58H

80
81
82
83
84
85
86
E7
88

(PROGRAMMER
D.5 CONCURRENT
ERROR)EXCEPTION
CODE
CODE

DECIMAL

HEXADECIMAL

E$PARAM

32172

8004H

BasicI/O Uset's Guide

D-3

E.1 LOGICAL
DEVICES
You can assigna logicalnameto any devicewith the I/O Systemcall
LOGICAIJATTACH$DEVICE. This createsa logicaldeviceobjeor,(T$LOG$DEV)
and catalogsthe objectin the root objectdirectory.
Tlpically, yoll usetheselogicaldeviceobjectswith l/O Systemcalls. However,BasicI/O
Systemcallsalsopermit the prefix parameterto be a Ìogicaldeviceobject. Whcn you use
a logicaldeviceobjectas tlìe prefir paramererin BasicI/O Sysremcalls,the BasicI/O
Systemlooks insidethe logicaldeviceobjectto determinethe deviceconnection.In such
cases,you couÌdreceivethe exceptioncodeE$DEV$OFF$LINE. Ifyou receivethis
exceptioncode and the deviceis online,the devicewasneverphysicallyanached.
Beforeyou can use a logicallynameddevice,the devicemustbe madeknown to the
system(attached),with the BasicI/O Systemcal A$PHYSICAIJATTACH$DEVICE.
But when LOGICAL:$ATTACH$DEVICE is invoked,the systemdoesnot immediately
issuea call to A$PHYSICAL$ATTACH$DEVICE. Instead,physicalattachmentoccurs
transparentlyduring processingof any I/O Systemcall which referencesthe logicaldevice
object.
You might createa logicaldeviceconnectionbut not invoke any I/O Systemcall to
perform the physicalattachoperation. Ifso, the BasicI/O Systemcan rerurn
E$DEV$OFF$LINE. You can correctthis situationby invokingat leastone I/O System
call that refersto the logicaldeviceby ìts logicalname (suchas :F0:). However,your tasks
must residein an I/O Job beîorethey can invokeI/O Systemcalls.

E.2 REFERENCES
For furtherinformation,
referto thedescriptions
of l/O Jobs,
LOGICAI$ATTACH$DEVICE,andA$PIIYSfCAL$ATTACH$DE\/ICEin the
ExtendedíRl,ÍXII ExtendedI /O SystemUser'iGuid".

BasicI/O User'sGuide

F,1 INTRODUCTION
The iRMX ll OperatingSystemis basedon theiRMX I OperatingSystem.Therefore,
the iRMX Il ve.sionof theBasicl/O Systemis alnostexactlylike theiRMX I version.
'lhe
samesysîemcallsareavailabÌe,
withno changes
or additions.But thereare
differences.
Thisappendixoutlìnesthedifferences
betweenfhetwoversionsfor readers
whoareaheadyfamiliarwirhrheiRMX I OperatingSystem.Thosewhoaren'tfamiliar
with the iRMX I OperatingSysîem
canskipthisappendix.

F.2 80285CAPABILITIES
Themajordifferences
betsr'een
theiRMX I andiRMX II versionsof theBasicI/O
Systemare a resultof theincreased
capabilities
of the80286/80386
processor-namely
16M-byte
addressabìlity
andmemoryprotection.

F.2.1 16M-ByteAddressability
The 16M-byteaddressabilityallowsdevicedrivers(both Intel-supplìedand user-written)
and applicationtasksto accessa full 16M bytesof systemmemory. Application tasks
must uselogicaiaddresses
to accessmemory. Logicaladdresses
take the form
selector:offset
On the other hand,devicecontrollerscontinueto usephysicaladdresses
(16M-by,tes
requiresa 24-bitaddress).Thereforeyour devicedriversmust know how to convert
logìcal addressesto physical addresses.'îhe ExtendedíRLIX II Deice Dive6 lJser'sGuíde
discusses
this technique.

BasicI/O User'scuide

F-1

iR]\TXO
I AND iRMXOII BASICI/O SYSTEMDIFTERNNCES

F.2.2MemoryProtection
The memoryprotectionfeatureofthe 80286/80386
processorprotectsyour codeand data
by preventingany task from rcadingor writing a segmentofmemory unlessit hasexplicit
accessto that memorysegment.It alsopr€ventsmemoryreadsor writes from crossing
segmentboundaries.Be.auseof this feature,any task that usesth€ A$READ systemcall
must havewrite accessto the segmentoi rnemoryusedas the memorybuffer. Likewise,
any task that usesthe A$WRITE systemcall must haveread accessto the segúent used
as the memorybuffer. The A$SPECIAL systemcall alsochecksfor the cotrect accessand
issuesan error code if the accesst!?e is not appropriatefor the intendedoperation.

F.3 DEVICEDRIVERS
Not alÌ the Intel-supplieddevicedriversfor iRMX I are includedin the iRMX Il
Operating System. Refer fo the Extended|RMX II I tetuctíveConfgurutíon tltility
Referehce
Manual for informationaboùtthe Tnteì-supplied
driversthat are available.

F.4 DISKINTEGRITY
FEATURES
TIìree othsr featureshavebeenaddedto the BasicI/O Systemthat havenothingto do
with the capabilitiesofthe 80286/80386
processor.AII three help to improvethe integrity
of data storedon namcdvolumcs.

F.4.1AttachFlags
The BasicI/O Systcmprovidesan indicationofthe integrityofnarìed volurnesand
namedfiles. Wheneveryou attacha namedvolumeor a namedfile, the BasicI/O System
setsa flag to indicatethat the volumeor lile is atrached.The volumetlag is set in the
volumelabel;the file flag is set in the fnodefile. Whenyou detacha volume or file, the
BasicI/O Systemclearsthe associated
flag. Although the BasicI/O Systemdoesn,rcheck
theseflagsto determinelile or volumeintegrity,you can checkthe conditionof a volume
by invokìngthe A$GET$FILE$STATUSsystemcall. If the flag js serfor a volume that
isn't currentlyattached,the settingcould indicatea corruptedvolumethat wasnI
detachedproperly.
The BasicI/O Systemdoesn'tprovide a systemcall for checkingthe file flag. However,
you can wnte your own pfogrdnÌsto checkthis flag,or you can userhe Disk Veriiication
UtiÌìty to examinethe fnode file.

F-2

BasicI/O Usefs Guide

iRMX@I ANDiRMX@II BASICI/O SYSTEMDIFFERENCES

F.4,2 FnodeChecksumField
The BasicI/O Systcmhasalsoaddeda checkum field to the fnode file. Thc tnodc lilc
storesthe informationthat the BasicI/O Systemneedsto a@essany namedfile on the
volume. menever the BasicI/O Systemwrìtesthe fnode file, it calculatcsa checksum
and storesit in the fnodefile. Althoughthe BasicI/O Systemdoesn,tcheckthe fnodefile
againstthe checksumwhen it readsthe fnodefile, your programs(?n se the checksùm
field to determinewhetherthe fnodefile hasbecomecorrupted.

F.4.3 Gettingand Settingthe BadTrack/SectorInformation
The A$SPECIAL systemcall hasbeenenhancedto retrieveand set the bad track/sector
informationon a volume. The bad track/sectorinfomation providesa list of the tracks
or sectorson the volumerhat are defective.One of the new A$SPECIAL subfunctions
allowsyou to retrievethe currentlist of defectivetracksor sectors.The other new
subfunctionenablesyou to set up a new bad track/sectorlist.

BasicI/O IJseÉsGuide

F.3

A
Actionsrequiredof thereadingtask
closethenewlile connection5-3
createa secondfile connecrion
for thesteam file 5-3
deletethenewfile conneclion5-4
getth€file connection5-3
open the new file conncction for reading 5-3

perforrn the requiredreads 5-3
Actions reqùired of the writing task
closethe connection 5-2
createthe streamfile 5-2
deletethe connection 5-2
obtain a connectionto the streamfile 5,1
open the file for writing 5-2
passthe file connectionto the readingtask 5-2
write the informationto the streamfile 5-2
Asynchronoussystemcalls 6-6

B
Bad track and sectorinformation 1-8
Basicl/O Systemfeatures 1-1
16M-byteMemory addressability1-2
accessto files,controlling l-5
deviceindependencel-3
file sharing 1-5
lour lile t'?es 1rl
namedfiles l-4
physicalfiles 1-4
remote files 1-5
streamfiles 1-zl
protectionfeatures 1"2
separationof File Lookup and File Open Operations 1-5
supportîor many kinds of devices 1-3
synchronousand asynchronous
operation 1-2

BasicI/O Use/s Guide

Index-1

I\DEX

BIOSperformance
factors7-3
devicegranularity7-3
file granularity 7-3
ti-rDebctwccn updates7-3
volumeg anularity 7-3

c
Callsthat return an I/O result segmentC-1
Checkingthe conditioncode retumed from a call C-1
Concuftentprogrammererrors D-3
Conditioncodes 6-10
Connectionbetweentasksand device-units2-2
Connectionsand physicalfiles 4-2
Controllingfragmentationof files 1-6
Creatinga file with an existingpathname 7-2

D
Data tlpes (seeAppend;( A)
Dcviceconnections2-4
Devicecontrollersand deviceunits 2-l
Disk integrity l-7

E
E$IOcodesreturnedin unit$starusC-2
Environmental
errors D-2
Environmental
exception
codesD-1
Exampleof usingasynchronous
systemcalls 6-7
Exception
codes(seeAppendixD)

F
File connections2-5
f ilc-pathparamelers
for namedfiles o-l
Fiìes 2-2
Fligs for namedvolumesand files l-8
Fnodechecksumfield 1-8

G
Global clock l-7
Granularityfor hard dìsks 1-7

lndex-2

BasicI/O User'sGuide

TNDEX

I
I/O buffersfor the A$READ and A$WRITE systemcalls 6-6
l/O resultsegment,structure C-2
ID, systemmanager 7 2
Intel devices7-1

L
LogicaldevicesE-l

M
Memory neededfor objects B-2

N
Number of buffersfor eachdevice 7-1

o
Object types B-1
Open-mode
indicator2-?

P
Pathsfor systemcallsreferringto namedfiles ó-3
Prefi\ parameterl

R
Respons€
mailboxparameter6-4

s
Sequentialprogrammererrors D-2
SeFr'ìc€
task prioritics 7-2
Share-modeindicator 2-7
Situationsrequiringphysicalfiles
formattingvolumes 4-1
implementingyour own file format 4-1
volumesformattedfor other systems4-1

BasicI/O I lsefs cìride

Ind€x-]

INDEX

Stepsfor usingphysicalfiles
closethe file connection4-3
deietethe file conne.ction4-3
detachthe device ,{-3
manipulatethe file 4-3
obtain a deviceconr€ction ,l-2
obtain a iile connection4-2
open the file connection 4-2
Stfuctureofthe l/O resultsegment C-2
Svnchronoussystemcalls 6-1
Systeminitializationerror reporting 7-2
Systemmanager 7-2

T
The two parts of asynchronous
systemcalls
the concurent part 6-6
the sequentialpart 6-6
Three typesof ganularity
device 1-6
file 1-6
volume 1-6
Timing facilities 7-2

U
Unit statuserrors for the iSBC 214/215c Controller C-3
L,serparam€ter 6-2
U\ing CET$TYPEro derermine if a ionneclionL'rrn
I/O ResultSegmenthasbeenreturned C-1
Usingphysicalfiles 4-2

V
volume granularityfor flexiblediskettes l-6
\ otumesl-2

fndex-4

Basicl/O User'scuide

intel"
E X T E N D EiD
R M X@II

EXTENDED
I/OSYSTEM
U S E R 'GSU I D E

nte Corporation
3065 Eowers
Avenue
S a n t aC l a r aC
, a l i f o r na 9 5 0 5 7

Copyrqht .- 1988. ntel Corporaion, All RrqhtsRese.ved

INTRODUCTION
This manualdescribesthe iRMX@II Extendedl/O System.Although it contarnssome
introductoryand overviewmaterial,it is primarily a detaileddescriptionof the Extended
I/O System.

READERLEVEL
Themanualis writtenfor programmers
whoareaLeadyfamiÌiarwith
.

The concepts and terminologr introduce<];n the Extended iRÀ,lXII Nucleus Uset's

CuAe.
.

The PL/M-286 pr ogramminglanguage.

Readersneed not be familiar with the iRMX l-t Basict/O Sysrem.

MANUAL
ORGANIZATION
This manualis dividedinto the fbllowingchaptersand appendixes.
Chapter 1

This chapterdescribesthe difTerences
betweenthe BasicI/O
Systemand the Extendedl/O System,You shouldread this
chapterif you are not certaìnwhich l/O systembestmeetsyour
requremenls.

Chapter2

This chapterdescribesthe primary featuresof the ExtendedT/O
System.You will find this chapterparticularlyusefulifyou have
not usedthe ExtendedI/O Systembefore.

Chapter3

This chapterexplainssomebasicterminolos/ associated
with the
ExlendedI/O System,includingthe followingterms: device,
volume,file, and connection.You shouldread this chapterif you
are lookingthroughthe manualfbr the first time or ifyou are
unfamiliarwith the ExtendedI/O System.

Chapters4 6

Thesechaptersdescribenamed,physical,remote,and streamfiles
and how to usethem. You shouldread one or more ofthese
chapters,dependingon the kinds of files your applicationuses-

ExtendedI/O User's Guide

lll

I'RIFACE

Chapter7

Thischapterdescribes
characteristics
of the Extended
I/O System
thatyouspecif whenyouconfigurean iRMX II OperatingSysteú.

Appendi\A

Thisappendixdefinestheformatsofthe dataq?esusedby the
ExtendedI/O SystemFor example,
it explains
theformatofan
iRMX II STRING.

AppendixB

Thisappendirprovidesa list ofthe q?esof objectscreatedby rhe
Extended
I/O System.It alsodiscusses
the resourcerequftements
of the Extended
I/O System.

Appendix C

This appencìixcontains a list of the condition codes that the

ExtendedI/O Systemcan return. The codesare listedrn
alphabeticalorder, and eachentry in the list includesthe
classificationof the code(programmererror or environmental
condition)and the nìimericvalueof the code.
AppendixD

The ExtendedI/O Systemusesobjecîdirectoriesextensively.This
appendixtellswhich entriesare ùsedby the ExtendedI/O System.
It alsotellsyou which entriesyou can changeand which entriesyou
can't.

AppendixE

This appenclixexplainsthe incompaîibilitiesbetweenthe system
callsof the BasicI/O Svstemand rhe svstemcallsof the Extended
I/O System.

AppcnrJixF

This appendi.(liststhe differencesber\À'een
rhe iRMX II and
iRMX I versionsof the ExtendedI/O Svstem.

CONVENTIONS
Thismanualusesthefollowingconventions:

The term"iRMX ll" refersto rheExr€nded
iRMX IL3 OperatingSystem.

The term"iRMX I" refcrs!o thc iRMX I (iRMX 66)OperalingSystem.

All iRMX I I systemcallsbeginwith oneof two standard
prefixesrRQgor RQE$.
Whenreferringto the systemcallsthaîbeginwith RQ$,thismanualusesa shorthand
notationandomitstheprefix. For example,
S$CREATE$FILE
means
RQ$S$CREATE$FILE.
The actualPL/M-286externalprocedure
namesusedto
invokethesesystemcallsare shownonly in the EÍendcd \RMXII ExtendedI/O Synem
CaIsRekrc & Manual,whichlisrsrhedetailedcallingsequences.

Extended
I/O Use/s Guide

PREFACE

WhenreferrirBto systcmcallsrhatbeginwirh RQE$,thismanualspellsout the
completenames,includingthe RQE$characters.
Therearesomesystemcallswhosenamesareidenticalexceptfor the Re$ or ReEg
prefixlfor erample.
theEIOSsystem
callsRe$CREATE$lò$JOB
and
RQE$CRbA]E$JOB).The difference
betweentwo similarlynamedsystemcallsis
that the RQ$versionoperates
asit did undertheiRMX I OperatingSystemandis
availabìe
for comparibility.
The ReE$ versionis updatedto supportnew802gó
features,
suchas 16Mbytememorypools.Unlesscompatibility
with iRMX I systems
is an issue,lntel rccommends
rhatyouuserhesysî€mcallwith rheReE$ preface
insteadofthe onewith the RQ$preface.

Extended
I/O Usefs cuidc

CHAPTEH
1
cHoostNG BETWEEN
t/O SYSTEMS

PAGE

CHAPTER 2
FEATURESOF THE EXTENDEDI/O SYSTEM

PAGE

ExtendedI/O llser's Guide

CONTENTS

CHAPTER
3

PAGE

CHAPTER4
NAMEDFILES

PAGE

vlll

Extended
I/O Uset'sGuide

CONTENTS

CHAPTER4 (continued)

PAGE

CHAPTER
5
PHYSICALFILES

PAGE

CHAPTER
6

PAGE

CHAPTER7
CONFIGURATION
OFTHEEXTENDED
I/O SYSTEM

PAGE

APPENDIX
A
DATATYf'ES

PAGE

STREAM FILES

Extended
I/O Uset'scuide

CONTENTS

APPENDIXB

PAGE

APPENDIX
C

PAGE

APPENDIX
D

PAGE

APPENDIX
E

PAGE

COMPATIBILITY
BETWEEN
THETWOI/O SYSTEMS

E.1 ConpatibiiìtyBetweenThe Two l/O Systems............................................................E-1

APPENDIX
F
iRMX@
IAND iRMX@
II ETTENDED
I/O SYSTEMDIFFERENCES

PAGE

Extended
I/O Usefs Guide

CONTENTS

FIGUFE

PAGE

3-l Layersof Interfacing
BetweenTasksand a Device,.,....,.,.........,.,..............................
32
3-2 Schematic
of Softwareat Inirializarion
Time............................-..................................
3-3
3-3 A Systemwith Deviceand File Connections.................-..............
................................3-4
4-l Exampleofa NamedFile Tree.................
..,...,........................
4-3
4-2 Computingthe AccessMaskfor a File Connection-....................
.............................4-13
4 3 Chronologyof FrcqucntÌyUsedSystemCallsfor NamedFiles.............................4-20

ExtendedI/O User'sCuide

CHOOSING

1,1 INTRODUCTION
The iRMX II OperatingSystemprovidesyou with a choiceof two l/O systems.One of
these,the Extendedl/O System,is describedin this manual. The other, the BasicI/O
System,is described in the E te ded \RMX II BasicI/O gstem Use* Guide.
This chapterexplainsthe reasonfor havingtwo I/O systemsand briefly describesthe
differencesbetweenthcm. After readingrhis chapîer,you shouldbe ableto decide
whetheryour applicarionrequiressystemcallsfrom both systemsor from just one. If one
of the T/C)systemsis sufficient,you shouldbe ableto decidewhich one.
As you read this chaprer,rememberthat the ExtendedI/O Systemis built upon the Basic
I/O System.In other words,ifyou choosethe ExtendedI/O System,you must also
includethe BasìcI/O S),stemin your applicarion.

1.2 REASONFORHAVTNG
TWOt/O SYSTEMS
The iRMX II OperatingSystemis designedro provideOriginal Equipmcnt
Manufacturers(OEMs) wilh a varietyof fearuresthat are usefulill buildingapplication
systems.Many of thesefeaturesare usefulin most,but not rll, applications.This is
e s p c c i a ltìryu eu f t e a r usr5r ( l i l i n gr ù i n p u ra n do u r p u l .
Most applicationscommunjcatewith externaldevicessuchas line printers,terminals,disk
drives,or bubblememories. Even so,not all applicationshavethe samerequirements.
The iRMX II OperatingSystemprovidestwo I/O systemsto allow you to choosethe one
that best satisfiesthe requirementsofyour applicationsystem.And, in the eventthat
both systemswould proveusefulin one applicarion,rhe iRMX II OperatingSystemallows
you to usethem both.

Extendedl/O Ilser's Cùide

l t

CHOOSINC BETWEEN I/O SYSTEMS

NOTE
All informationon iRMX Neîworking
Software(iRMX-NET)canbe
foundin the,RMXNetworking
Software
UserSGarZ".CoÍsultthismanual
for informationon howto sharefilesanddatain a distributed
envftonment
with separate
iRMx-basedworkstations.
TheI'RMX
Netwo*jhg SoftuareUser'gGuAe ís nor part of the iRMX II
documentation
set.

1.2.1 Basicl/O Sysiem
The Basicl/O Systemis the more flexibleofthe two I/O systems.It providesvery
powerfulcapabilities,ald it makesfew assumptions
aboutthe requirementsofyour
application.The followingfeaturesillustratethe fleribiìity of rhe BasicI/O System:
.

AILOWS YOU TO DESIGN YOUR OWN BUFFERING AIcOzuTHM
Although many applicationsrequirebufferedI/O, rhe BasicI/O Systefl doesrìor
automaticallyprovide ìt. Ratherthan requireone parricularapproachto bufferedT/O
for all applications,the BasìcI/O Systemalows you to designand imptementyour
own bufferingmethod.

SUPPLIESASYNCHRONOUS SYSTEM CALLS
Rather than makingassumptionsaboutwhether(and how) you wish to overlapyour
I/O operations,the BasicI/O Systemallowsyou to explic;rlycontrol the
synchronizationof the systemcalls.

GIVES YOUR TASK CONTROL OF DETAILS
The systemcallsof the BasicI/O Systeminvolvemanyparamerers.Using these
parameters,your taskscan closelytailor the behaviorof eachsystemcall to rnatchthe
requirementsof your àpplic;ìtionsystem.

As thesefeaturesshow,the Basicl/O Systememphasizes
fleúbility rather than easeol
use. By preservingflexibility,the Basicl/O SystemprovidesI/O featuresîhat are useful
in a wide rangeof applications.
Clearly,the BasicI/O Systemdoeshavelìmitations. Many applicationsrhar perform I/O
do not needthe control ofdetails affordedtry tlìe BasicI/O Sysrem.For many
applications,the amountof time requir€dto developthe applicationsystemis more
critical than the ability to finely tune its pe.formancc. For thcseapplications,the iRMX
Il OperatingSystemprovidesthe Efended I/O System.

t-2

Extended
I/O User'sCuide

CHOOSINGBETWEENI/O SYSTEMS

1.2.2 Extendedl/O System
The ExtendedI/O Systemis designedto be easicrro userhan the BasicI/O System.Thc
followingfeaturesofthe Extendedl/O Systemhelp make it easierto use:
r

AUTOMATIC BUFFERING OF l/O OPERATIONS
The ExtendedI/O Systemprovidesyou with automaticbLrfferìngof all I/O
operations.Aside from specif ing how manybuffersthe Extendedl/O Systemuses,
your tasksneed not becomeinvolvedwith buffering. Furthermore,ifyour application
systemdoesnot requirebuffering,your taskscan tell the ExtendedI/O Systemto use
no buffers.

S\î.ICHRONOUS SYSTEM CALI.S
The ExtendedI/O Systemprovidessystemcallsthat are synchronous.By freeingyour
applicationsoftwarefrom the burdenof explicitlysynchronizingsystemcalls,the
ExtendedI/O Systemreducesthe complexityofyour appìicationsystem.This, in turn
helpsreducedevelopmentcosts.Although the systemcallsof the Extendedt/O
Systemare synchronous,
your applicationsystemcan still useoverlappedI/O
operations.To do so,your tasksneedonly tell the ExtendedI/O Systemto use
buffers,and the ExtendedI/O Systemwill automaticallyoverlapyour l/O operarions.

FREES YOUR TASKS OF TEDIOUS DETAILS
The systemcallsof the ExlendedI/O Systemrequirefe$er pa.ametersthan cloihosc
of the BasjcI/O System.This simplifiesyour applicationsystemand reduces
dcvclopmentcosts.

1.3 MAKINGTHEDECISTON
At thispoint,youarefacedwith threealternatives.
ShouldyouusetheBasicl/O System,
theExtendedI/O System,
or both? To makethisdecision,
decideifyou. application
systemrequiresthe Uexibilit),
andfinetuningof the BasicI/O System,
theeaseof useof
the Extended
I/O System,
or a combinarion
of both. Befbre)ou makethetinal decision,
consicler
the followingrwofactors.

ExtendedI/O Usefs Guide

l --l

CHOOSING BETWEENI/O SYSTEMS

1.3.1 MemoryRequirements
The ExtendedI/O Systemsoftwarerequiresthe BasicI/O System.The sizeof the
ExtendedI/O Systemsoftwareis approximately19K byres.Ifyour applicationsystemis
pressedlbr memoryand doesnot requirefeaturesof the ExîendedI/O System,you can
savethe l9Kbytes of memoryby usingonly the BasicI/O System.
However,ifyou decideto use the BasicI/O Systemeventhoughyour applicationsystem
needsthe featuresof the ExtendedI/O System(suchas buffering),you might end up
usingall 19K b)'tesof memoryimplementingthesesamefeatureson top ofthe BasicI/O
System.
Be awarethat usingboth the BasicI/O and ExtendedI/O Systemsrcquircs no more
memorythan ùsingthe ExtendedI/O Systemalone.

1.3.2 Performance
Becausethe Basicl/O Systemgivesyour applicationsystemcontrol of many details,you
can probablytune your applicationsystemto run fasterwith the BasicI/O Systemthan
with the ExtendedI/O System.So if performanceis more important than reduced
developmentcosts,you shouldconsiderusingthe Basicl/O System.Ifyou decideto use
the Efended l/O System,you can improveperformanceby changingthe buffer stzes.

1.4 EXAMPLES
The followingexamplesillustratethe advantages
of eachof the I/O systems.The analysis
in eachejrampleis basedon the assumptionthat many copiesof the applicarionsysrem
are to be oroduced.

1.4.1 Application
SystemsUsingLittlet/O
Supposethat your applicationsystemrequiresvery little I/O. For instance,supposethat
its only I/O activityis to occasionally
log informationro a flexibledisk.
Becausethis applicationsysteminvolvesvery few l/O-related systemcalls,the BasicI/O
Systemis preferableto the ExtendedI/O System_The easeof useprovidedby the
ExtendedI/O Systemcan saveyou very little manpower(hencemoneyand time) during
developmentbecausethe I/O-related part ofyour systemrequiresso little time to
develop.This marginalbenefit is of lessuseîo your applicaîionsystemthan is the 19K
b).tesof memorysavedby usinglhe BasicI/O Sysrem.

l -;t

Extended
I/O User'sCuide

CHOOSING BETWEENI/O SYSTE}IS

1.4.2 ApplicationSystemsUsingOntySequentialt/O
Supposethat your applicationsystemrequiresa substanrialamountof sequentialI/O. In
this t'?e of system,a large amountofyour developmentresourceswill be expenclecl
in
supportofI/O. This factorshouldmakeyou considerusinglhe ExrendedIfO Systemto
reduceyour staffingrequìrementswhile developingthe applicationsystem.
A secondtactor shouldalsosteeryou toward the ExtendedI/O System-thesequential
I/O. The br,rfferingschemeusedby the ExtendedI/O Systemis particularlyefficient
while performingsequenliatI/O becauseit incorporatesread-aheadand write-behincl
algorithmsto overlxpI/O operationsand processing.
Thesetwo factors,the amountof manpowerrequiredto implementI/O and the
sequentialnature of the l/O, combineto make rhe ExrendedI/O Systemthe bestchoic€
for this applicationsystem.

1.4.3 High Performance
ApplicationsUsingRandoml/O
Now supposethat your syslemperformsa largeamountof random-access
I/O, and
supposethat performanceis a critical considerationthat overrìdesconcernsaoour
conservingmemory. You shouldconsiderthe ExtendedI/O Sysîembecause,in thìs
applicationsystem,it can substantiallyreduceyour developmentcosts. However,lwo
other factorscombineto makethe BasicI/O Systemanotherreasonablechoice.
Th€ lirst factor is the randomnatureof lhe l/O. The read-aheadand write-behjnd
algorithmprovidedby the ExtendedI/O S),sremis not particularlyefficient in randomacccssI/O operations.The secondfactor is the lequirexr€rt tor pcrformancc. Using thc
BasicI/O Systeú as a foundation,you can build an I/O facilirythat takesadvantageof
you. appljcationsystem'sknowledgeof the organizationof data in the files. Although
sucha faci[ty might be expensiveto implement,it shouldrun fasterthan the E\tended
I/O Systemin this application.
So in this case,you must weìghthe cost of developmentagainstthe benefitofbetter
performance.lf developmentcostsare more important,you shouldusethe ExtendedT/O
System.If performanceis more important,you shoulduse the BasicI/O System_Atso,
don't ignorethe option of usingthe Extendedl/O Systemto createa prototype
applicationsystemand then later replacingthe ExtendedI/O Systemwith your custom
I/O faciiity.

ExtendedI/O UseÈsGuide

t-5

CHOOSINGBDTWEENI/O SYSTEMS

1.5 SUMMARY
In general,you shouldconsiderthe BasicI/O Systemfor applicationsthat requirevery
little I/O, o. for applicationsr€quiringfinely-tunedperformancewhile doing randomaccessI/O. ln contrast,you shouìdconsiderthe ExtendedI/O Systemwhen development
costsare critical,especiallyin applicationsthat useseqùentialI/O.
Finally,rememberthat there are circumstances
whereyou shoulduseboth I/O systems.
One suchsitùationoccurswhenyour appÌicationsystemusesI/O for severalpurposes,
someof which are best accomplished
by the Basicl/O System,and othersby the
ExtendedI/O System.

t-6

Extended
I/O User'sCuide

2.1 INTRODUCTION
Becausethe ExiendediRMX II Extended1/O Systemis designedprimarily for useby
Original EquipmentManufacturers(OEMs), it providesa large numberof featuresincludingsomethat are not generallyfouÍd in operatingsystemsaimedat end users.
Thesefeaturesinclude
.

Memory protection

Supportfor many kinds of devices

Device independence

Four distinctkindsof files

File independence

Separationof filc-lookup and file-openoperations

File sharirg and accesscontrol (supportfor iRMX-NET)

Bufferingwirh overlappedI/o

Logicalnamesfor files and devices

Automatic reattachmentof devices

16M-bytememoryaddressabiliry

The first eight of thesefeaturesare implementedby the BasicI/O Syst€m.Howcvcr,
becausethe ExtendedI/O Sysîemusesthe facilitiesprovidedby the BasicI/O System,
the ExtendedI/O Systemalsoprovidesthesefeatures.The balanceof the featuresare
availableonly with the ExtendedI/O System.

2.2 16M-BYTE
MEMORY
ADDRESSABILIW
The iRMX ll OperatingSystemruns in the protectedvirtuaÌ addressmode (PVAM) of
thc 80286and {ì038óproccssors.As a result,it can accessas rnuchas lúM lrytesof
memory. The ExtendedI/O Systemtakesadvantageof this featr]reby allowingyou to
createI/O jobs wìth memorypoolsof up to 16M bytes. Therefore,tasksthat invoke
Erlended I/O Systemcallscan havemore codeand can havemore room for data.

E(ended I/O Uséris cuide

FEATfIRIS OF THE EXTENDED I/O SYSTEM

2.3 PROTECTION
FEATURES
Becausethe iRMX II OperatingSystemaccesses
the processorin PVAM, it benefitsfrom
someof the inherentmemoryprorectionfeaturesof lhe processor.Thesefealures
protectyour code and data by preventingany task from readingor *riting buffersof
mcmory unlessit hasexTrlicitaccessto thosebuffers. They alsopreventmemoryreadsor
writes from crossingsegmcntboundaries.The OperatingSystemgeneratesexception
codesif an attemptedprotectionvioiatioo occurs.
The OperatingSystemalsocheckssystemcall parametersfor protectionviolationsand for
incorrectvalues.Appendi\ C ìiststhe exceptioncodesthat canbe returned.

2.4 SUPPORTFORMANYKINDSOF DEVICES
The ExtendedI/O Systemsupportsa wide varietyof devices.To connecta particular
deviceto the Extendedl/O System,your.pplicxtion systemmust includea devicedriver
(a collectionof softwareproceduresiÌnplementedat the BasicI/O Systemlevel) for the
devicebeingconnected.The OperatingSystemprovidesyou with driversfor flexibleand
hard disks,line printers,serialterminals,bubblememorìes,and many other devices.A
completelist of devicesthat are supportedby the OperatingSystemis ìncljded in the
Ettetvled iRMX II Inteructire CanfrguratianUtilù!- ReferenceManuaL along with detailed
instructionsfor includingspecificdriversin your applicationsysrem.
Ifyou need driversfor devicesother than thosefor which Intel suppliesdrivers,you can
writc drivcrsthat are compatible$'ith the iRMX lI OperatingSysren'ì.For specific
instructions.refer to the ExtendedíRMX II DeviceDirerc User'sGuíde.

2.5 DEVICE
INDEPENDENCE
The Extendedl/O Systemprovidesyou with one set of systemcallsthat can be usedwirh
any collectionol devices.For ìnstance,rather than usinga TYPE sysîemcall for output to
a terminal and a PRINT svstemcall for output to a line printer, you can usea WRITE
systcmcall for output to any device.
This notion of one set ofsystemcallsfbr I/O to anv collectionof devicesis calleddevice
independence,
and it providesyour applicationwith a lot of flexibility. For example,
supposeyoul applicationIogsevenlsas they occur The deviceindepencìence
ofthe
ExtendedI/O SystemaLlowsyou to createan applicationthat can log the eventson any
devicerather than on just one- When the applicationis runningand circumstances
force
an operatorto reroute loggingfrom the tele5?ewriter to the line printer or disk,your
applìcationcan easìlycomply. For a more detailedexplanationof deviceindependence,
releî fo lhe Introduction to tlrc Ettended |RMX ll Operatingstttem.

:-l

Extended
I/O User'sCuide

FEATURNS
OF THE EXTENDEDI/O SYSTEN'

2,6 FOURKINDSOF FILES
The BasicI/O Systemimplemelltsfour rJistincrkindsof files,and rhe ExtendedI/O
Systemsupportsall four. Each kind offile is byte-oriented,rather than record-oriented_

2.6.1 NamedFiles
Namedfiles are intendedfor usewith random-access.
secondarv-storaqe
devicessuchas
disk drives,diskettedrives,ancìbubblcmemories.Named fileslllowyirur applicationto
organizeits files into a treeìike, hierarchicalstructurethat reflectsthe relationships
betweenthe files and the applicarion.Furthermore,only namedfiles allow your
applicationto store more than one file on a device,and only namedfiles provide your
applicationwith accesscontrol. Namedfiles alsoprovìdeyou with a good foundatjonfbr
buildingcustomaccessmethodssuchas ISAM (indexedsequentialaccessmethod).
For more detailedinformatìonregardingnamedfiles, read Chapter4 of this manual.

2.6.2 PhysicalFiles
Physicalfiles differ from namedfiies in that physicalfiles allow your applicationmore
direct control over a device. Eachphysicalfile occupiesan entire device,and applications
can dealwith the file as thoughit were a srringof bytes. However,physicalflles do not
provide accesscontrol. This more-basicrelationshipwith a deviceprovidesyour
applicationwith flexibility. For exarlple,your applicarioncan usea physìcalfile ro
interpret volumescreatedon other systems.
Physicalffes alsoprovideyour applicarionwith the ability to communicatewith devices
that do not needthe powerof namedfiles. Severalexamplesof suchdevicesare line
p.inters,dispìaytubes,plotters,and robots.

2.6.3StreamFiles
Streamfiles providea meansfor t\yo tasksto communicatewith eachother. One task
writes into the file while the other task concurrentlyreadsfrom it. Streamfiles useno
devicesand provide no accesscontrol.

2.6.4 RemoteFiles
The Extend€dI/O Systemcan alsoaccessremotefiles throughOpenNET. For more
information on accessing
remotefiles,consultfheíRMX NetúorkíngSoftuareUser's(;uiLle.

ExtendedI/O User'scuide

[.EATURESOF THE EXTENDED I/O SYSTEM

2.7 FILEINDEPENDENCE
Systemcallsfor readingand writing work with any of the q?es of files describedearlier.
This allowsyou to createtasksand applicationsthat can be readilyswitchedfrom one
kind of file to another.
For example,your applicationmight involvetwo tasksthat mustcommunicateby usinga
streamfile. ln the processof developingthe applicationsystem,you might implementthe
writing task beforeyou implementthe readingtask. For the purposeof debuggingthe
writing task,you can usea namedfile on a disk so you can examinethe informationbeing
written. L1ter, after you implementthe readingtask,you can route the ìnformationto the
streamfile rather than the disk.

2.8 SEPARATION
OF FILELOOKUP
ANDFILEOPENOPERATIONS
Many operatingsystemswastevaÌuabletime by lookingup a file wheneveran apptication
tries to open one. The iRMX lI ExtendedI/O Systemavoidsthis overheadby usinga
specialtype of iRMX ll object(calleda file connection)to representthe bond between
the file and an applicationprogram.
Wheneveryour applìcationsottwarecreatesa file, the iRMX Il ExtendedI/O System
returnsa file connection.Your applicationcan then use the connectionto open the file
without sulferingthe expenseofhaving rhe ExtendedI/O Systemlook up the file. Even
whenyour applicationopensan exislingfile, rhe applicrrioncan presenrthe file
connectionand bl?assthe file-lookupproccss.
File connectionsprovide a secondbenefit,one that reìatesto ac.esscontrol Any
connectionto a namedfile embodiesthe accessrights to the file. This meansthar the
ExtendedI/O Systemcomputesaccessonly once(whenthe file connectionis created).
rather than eachtime the file is opened.
Anolher benefit of file connectionsis that severaloi them can simultaneously
existfor the
samefile. This allowsseveraltasksto concurrenllyaeess ditferenrlocationsin the file.
This is possiblebecauseeachfile connectionmaintainsa poinleato keeDtrack of the
locationwirhinthe lile whcrerhe raskis reaJingor wriring.
lfyou plan to accessremotefiles throughOpenNET,consultthe |RMX Networkíng
Solírarc User'sGuide. That manualexplainshow to aocessiRMX Il-bas€dfiles thar
aesideon remote hardware.

2.9 FILESHARINGANDACCESSCONTROL
The Extended
I/O System
providesyourapplicarion
with rheabiliryto sharefilesand,in
the case ofnamed files. to control accessto files.

2-1

Extended
I/O Useascuidc

FEATURXS
OF THE EXTENDEDI/O SYSTEII

2.9.1 Fil6Sharlng
In a multitaskingsystem,it is oftel uselulto haveseveraltasksmanipularinga file
simultaneously.For example,considera transactionprocessingsystemin which a large
numb€rof operatorsconcurrendymanipulatca commondata base. If eachterminal is
driven by a distincttask,the only way to irnplementan efficienttransactionsystemis to
havethe tasksshareaccessto the data-basefile. The ExtendedI/O Svstemallows
multipletasksto accesq
the samefile ar the sametime.

2.9.2AccessControl
Also usefulin a multitasking
systemis the abilityto controlaccess
to a file. For instance,
suppose
thatseveralengineering
departments
sharea computer.An engineerin one
department
maywantto controlaccess
to filesasfollows:
.

Allow the ability to read,writc, and deletefil€s.

Allow other engineerswithin the departmentto read and wriie the files,but deny
them permissionto deletethe files.

Allow engineersof other departmentsto or y tead the files.

Namedfiles provideyour applicationwith preciselythis kind ofaccesscontrol.
For more detailedinformationregardingaccesscontrol,read Chapter4 of this manual.

2.10 BUFFERING
WITHOVERLAPPED
I/O
The ExtendedI/O Systemprovidesbufferingandoverlapping
of I/O operations.

2.10.1 AdvantagesOf UsingBuffers
Wheneverone ofyour applicationptogramsopensa connection,the programmust
specirythe numberof buîfersto be providedby the ExtendedI/O System.The numberof
buffe.s thaf your program.equestsaffectsthe actionsof the ExtendedI/O Systemas rt
readsand writes infotmation throughthe connection.SpecificLlly
.

Zero Buffers
The Erfended I/O SystemactuàÌlyaccesses
the file eachtime your applicationinvokes
a read systemcall or a write systemcall. For example,if your applicationcode asks
the ExtendedI/O Systemto read 30 bltes, the Erlended I/O Systemarcessesthe file
and readsexactly30 bytes. If the file resideson a physicaldevice,suchas a disk,the
ExtendedI/O Systemaccesses
the file for eachread or write request.

Extended I/O User's cuide

FEATURESOF'THE EXTENDED I/O SYSTEM

One Buffer
The ExtendedI/O Systemreadsand writes informationone buffer at a time. For
instance,when your applicationprogramasksthe Efended I/O Systemto read 30
bfes, the Systeminsteadreadsenoughinformationto fill the entire buffer. Using this
method,the ExtendedI/O Systenmight be ableto satisf severaladditionalrequests
without readingthe file again.
This methodoftransferring a firll buffer at a time is calledblocking. Blockingcan
significantlyimprovethe performanceof an applicationsystemby reducingthe
numberof times the ExtendedI/O Systemmust actuallytransferinformationto or
from a file on a device. In general,blockingis more valuablein sequentialI/O than rn
random I/O.
Two or More Buffers
IIyour applicationrequeststwo or moaebuffers,the ExtendedI/O Systemcan
overlapI/O operationsby usingread-aheadand write-behindalgorithms.
Readingaheadand witing behindare techniquesfor allowingtasksto continue
runningiahilethe ExtendedI/O Systemis transferringìnformationto or from devices.
Both techniquesare particularlyusefulwhenyour applicationis performingsequential
(rather than random-access)
I/O. This is becausethe ExtendedI/O Systemcan
accùratelydetermirìe,during sequeittialr€adingor writilg, the locationof lhc ncx!
data requiredby the application.
When you configurethe OperatingSystem,you specifythe maximumnumberof
buffersthat the Ertended I/O Systemcan usefor files on a particulardevice. The
numbe. of buffersfhar the ExrendedI/O Systemactuallyuseswhen readingor writing
a file is the lesserof this mzximumvalueand the numberof buffersspecifiedwhen the
file is opened. The S$OPEN call is describedin the trrelded íRMX II ExtetuledI/O
SvstemCalls ReferenceMantnl.

2.10.2ButferSize
Ifyou are responsiblefor configuringyour applicatìonsystem,you shouldbe awarethat
buffer sizesare,at leastpartially,a functionofsome parametersthat you set during the
configurationprocess.The next two paragraphsdiscusstheseparameters,However,if
you are not involvedwith configurationofyour system.you can skip over these
paragraphswithout missingany crucialinformation.
When your applicationrequestsone or more buffers,the Enended I/O Systemcomputes
the sizeof the buffersas a function oftwo configurationparameters--the
granularityof
the device,and the internal bulter sizeofthe ExtendedI/O System.The granularityis a
BasicI/O Systemconfigurationparamete.,and the internal buifer sizeis an Erlended
I/O Systemconligurationparameter. For more inlormafion abou!configuration,refer to
Chapter7.

2-6

ExtendedI/O Use/s Guide

FEATURXS
OF THE EXTENDEDI,/O SYSTIìN{

Whenyourapplication
programopensa connection,
the Extended
I/O Systemcreates
buffersequalto thelargestintegralmultipleof thedevicegranularity
thatdoesnot exceed
the inlernalbuffersize.Therearetwoexceptions
to thisrule:
.

If the devicegranularity
is zero,theExtended
I/O System
createsbuffersequalto the
internalbuffersize.

If the device granularity is greater than the internal buffer size, the Extended I/O
System creates buffers equal to the internaÌ buffer size.

2.11 LOGICAL
NAMESFORFILESANDDEVICES
The Extended
I/O Systemallowsyourapplication
programto uselogicalnamesto refer
to filesanddevices.A logicalnameis a slringof characters
thatthe Extended
I/O System
associaîes
with a particularfile connection
or deviceconnection.(A deviceconnection
rclates to deviccs in the same way that a file coonecrion relarcs ro filcs. Rcfcr ro

Chapter3 ofthis manualfor a precisedefinition.)
Youcanmakea logicalnameavailabie
to onejob,to a groupofjobs,or to all jobsin the
system.Thisis aocomplished
by cataloging
thenamein thelocaljobobjectdùectory,the
globaljob objectdirectory,or therootjob'sobjectdirectory,respectively.
(Chaprer3
describes
thesedire.tories.)

2.12 AUTOMATIC
REATTACHMENT
OF DEVICES
The ExtendedI/O Systemconstantlymonitorsthe srarusof deviccs.Whcn an opcrator
removesa diskette(or any other removablemedia)from a drive that is capableof
detectinga volumebeingremoved.the ExtendedI/O Systemdetachesthe deviceand
deletesall connectionsto files on the device. Whenthe ooeratorreDlacesthe removed
media,the ExtendedI/o Systemautomalicallyre-artach;srhe devi;e as soonas it is
accessed,
makingit availableto the tasksin your system.
Somedevices,suchas some5.25-inchflexiblediskettedrives.cannotdetecta volume
beingremovedfrom the drive. For thesedevices,the ExtendedI/O Systemcannot
pcrlbrm automatìcreattachmen!,

Extended I/O User's Gu;de

3.1 INTRODUCTION
Beforeyou usethe ExtendedI/O System,you shouldunde$tand severalfunclamentat
concepts.Someof thoseconceptswerepresentedin Chapter2. The remainingconcepts
are
.

DeviceControllersand DeviceUnits

Volumes

Files

Connections

I/o Jobs

LogicalNames

The followingsectionsexplaintheseconcepts.

3.2 DEVICECONTROLLERS
AND DEVICEUNITS
Devicesare suchthingsas flexiblediskettedrives,line printers,terminals,card readers,
and the like. A deviceis a hardwareentity that taskscan useto read information,write
information,or do both. More precisely,theseare deviceunits.
The iRMX II OperatingSystemdistitguishesbetweendeviceunits and the hardwnre
intedacesthat control deviceunits. The latter interfacesare calleddevicecontrollers.
Typically,a devicecontrollerallowsiRMX Il applicationsoftwareto communicatewiîh
severaldeviceunits. For example,an iSBC 214 WinchesterDisk Controllerboard acrsas
an interfacebetweenapplicationsoftwareand severalWinchesterdisk drives(device
unlts).

3.3 VOLUMES
A voÌume is the medium uscd to store the information on a device unit. For exalì4rle,if
the device unit is a flexible disk drìve, the volume is a diskette; and if the device unit is a
multi-platter hard disk drjve, the volume is rhe disk pack.

Extended
I/O User'sGuide

3-l

FUNDAMENTAL
CONCEPTS

3.4 FTLES
Someoperatingsystemstreat a file as a device,ìrhile otherstreat a file as information
storedon a device. The ExtendedI/O Systemconsidersa file to be information.
The Efended I/O Systemprovidesfour kinds offiles: physical,named,stream,and
remote. Each kind hascharacteristics
that make it unique. Chapter2 providesgeneral
informationabout eachkind of file. Chapters4, 5, and 6 provide more detail about
'Ihe
named, physical, and stream tiles.
|RMX Netroking Sof,{are User'sGuide pto'rides
detailedinformationaboutremotefilesRegardlessofthe kind of file, the ExtendedI/O Systemprovidesìnformationto
applicationsas a strìngofbt'tes,rather than as a collectionofrecords.

3.5 COMMUNICATION
CONNECTIONS
BETWEEN
TASKSAND
DEVICEUNITS
In complexenvironments,
suchasthosesupported
by the iRMX II OperatingSystem,
several
laye$ of softwareandhardwaremustbeboundtogetherbeforecommrinication
betweerapplication
tasksanddeviceunitscancommence.
Figùre3-1showstheselayers.

Figure 3- l, Layers of Interfacing BetweenTasks and a Device

Extended
I/O Useascuide

FUNDAMENTAL
CONCEPTS

3.5.1 InterlayerBondsPrecedingInitialization
The honclbetweena devicecontrollerand the d€viceunits that it controlsis g ohvsical
bond,ùsuallyin the form ofwires or cables.
A devicedriver is bound to devicecontrollersby dataresidingin a data structureknowt
as a DeviceUnit InforrnationBlock (DUIB). You supplythe data for DUIBS when
configuring the Operating System. Refer to the Etended íRMX Il DeviceDivers Llser's
6rode for more informationaboutDUIBS.
Apptcation softwareis boundto the file driver during the tinking process.you supplythe
informationnccdcdto perform the bindingprocesswhenconfiguringthe sysrem.
When your applicationstartsup, thesethree bondsare in place,Ieavingonly one gap
betweenthe layers. Figure 3 2 illustratesthis situation. The nevrelement,shownin the
figure as the configurationintertace,is the "glue"that providesthe final bond.

^ 055

figure 3-2. Schematicof Softnare at Initialization Time

Extended
I/O User'sCuide

FUNDAMENTAL
CONCEPTS

3.5.2Post-lnitialization
Bond- theConfiguration
Interface
The configurationinterfaceprovidestwo kindsof systemcalls. Before a task can use a
file, both of thesekjnds of callsmust be invoked. One type of call producesa device
connection,and the other a lile connection.Thesetwo NDesofconnectionsare shownin
Figure 3-3. Deviceconnectionsare depictedas conrJuits(pipes):file connectionsare
shownaswies throush the conduits.

Figure 3-3, A Systemwith Deviceand File Connections

3-4

Extended
I/O User'sGuide

FUNDAMENTALCONCEPI'S

3.5.2.1Oevice
Conneclions
To use a devicefor Eferìded I/O Syst€mcalls,tasksmust first invoke the systemclll
LOGICAL$ATTACH$DEVICE. which
.

Createsan objecttypecalleda logicaldeviceobject-alsorelèrred to as a device
connealion-'lhàî
repre\ents
thc Je\ ice.

Catalogsa token for the new objectunder a logicalnamespecifiedin the
LOGICAII$ATTACH$DEVICE caÌI. (A later sectionin this chapterdiscusses
logicaÌ
namesin detail.)

Identiliesthe ownerof the deviceconnection,to prev€ntother usersfrom detashing
devicesthat they do not own.

After LOGICAI$ATTACH$DEVICE is invoked,the logicalnameis associatedin the
objectdirectorywith a token for the logicaldeviceobject. The ExtendedI/O Systen
accesses
the deviceby usingthis logicalname.
3.5.2.2 FileConnections
When an applicationtask accesses
a deviceunit, it must usethe logicalnamelor that
deviceunit to obtain a file connectionobject. The file connectionrepresentsa particular
file on a devic€unit. How the tîsk ohtains the connectiondependson whetherthe fìle
alreadyerists. If the file alreadyexists,the task usuallycallsS$ATTACH$FILE, aÌrhough
it can alsocall S$CREATE$FILE. Ifthe file doesnot vet exist.the task must call
S$CREATE$FILE.

NOTE
You can call S$CREATE$FILEto obtain a file connectionfor a fiie that
alreadyexists.But, for the followingreason,you shouldavoid using
S$CREATE$FILE unlessit is certainthat the file doesnot yet exist.
Calling S$CREATtr$FÌLEto obtaina connectionfor a file rhat aLeady
existstruncatesthe iile to zero ìength. Even ifyou do this deliberately,
truncatingcausesproblemsfor taskshavingother connectionsto the file,
becausethe file pointers(discussed
later in this section)for thoseother
conneltionsare not affected,eventhoughthe end-of-îilemarker is moved
to the beginningofthe file.
You shouldobservethis precautionevenwlìenobtainingconncctionsto
physicalor streamfìles,becauseyou might want to usethe samecodeto
obtain connectionsto namedfiles.
Unlike deviceconnections.there can be multiple file connectionsto one file. This allows
different tasksto havedifferent kindsofaccessto the sameflle at the sametime, as the
nextparagraphshows.

EYtended l/O Use s Guido

r-UNDAMENTAI CONCEPTS

After receivinga file connection,
a taskcallsS$OPENto opentheconnection,
Parameters
in thecallto S$OPENspeciryhowthetaskinrendsto usethe file connection
andhowit is willingto sharethefìlewith othertasks.

NOTE
If a task iú onejob obtainsa file connectionthat wascrearedin a diîferent
job, the task cannotsuccessfully
use the connectionto perform I/O
operations.However,the taskcan catalogthe connectionunder a logical
name,and usethe logicaÌnamein the ATTACH$FILE systemcall to
obtain a secondconnectionthat can be usedwithout restriction.

3.5.2.3FilePointers
The Erlended I/O Systemmaintainsa file pointer for eachopen file connectionto a
random-access
deviceunit. This file pointer telis the ExtendedI/O Systemthe logical
addressof the bytewherethe nextI/O operationon the lile is to begin. The logicat
addresses
of the bytesin a file beginwith zero and increasesequentiallythroughthe
entire file. Normallythe pointer for a file connectionpointsat the nextlogicalbyte after
the one most recentlyread or written. However,a task can modi$ the file pointer by
invokingrhe S$SEEKsystemcall. This seekingprocessis particula.lyusefulwhen
performingrandom-access
(as opposedto sequential)operationson a file.

3.5.2,4SomeObservations
aboutDevices
andConnections
Figure 3'3 is quite detailedand showsmost of the situationsthat are possiblefor device
units and file connectionsto them. In pafticular,you can observethe followingaboutthe
figure:
.

ì-)e,r,ice
connectionsextendfrom the applicationsoftwareto the individualdevice
units,and eachpassesthroughone and only one file driver.

There is only one d€vicecoùÌecti()nto eachconnecteddevice. However,multiple file
connectionscan sharethe samedevtceconnecuon.

Different deviceunitswith the samecontrollercan be connectedvia dìfferentfile
drivets.

Taskscan shareaccessto rhe samedevjceunit throughthe physicalfile driver, and
they can shareaccessto the samefiles on the samedeviceunit throughthe namedfìle
driver.

There is only one deviceconnectionthroughthe streamfile driver, becauseone logical
devìcecontainsall streamfiles.

The configurationintcrface,whichis depictedas a pile ofconduiîs,is off ro one side.

All but one of the deviceunits are connected.The unconnecteddeviceunit is still
separatedfrom the applicationsoftwareby the configurationinterface.

Extended
I/O Us€r'sGuide

FUNDAMENTALCONCEPTS

3.6 LOGICALNAMES
Logicalnamcsidentify file connectionsor deviceconneoions. More specifically,you
catalogthe tokensfor file connectionsor deviceconnectionsunder ìogicalnames. This
sectiondescribesthe syntaxfor logicalnames,and then describesthe directoriesin *hich
you catalogconnectionsunderlogicalnames.

3.6.1Syntaxfor LogicalNames
A logicalnameis a STRING of 12or fewer characterswith the followingcharacterisrics:
.

l he ASCII codelbr eachcharactermustbe between020hand 07Fh. You cannotuse
a slash(/), ar up-arrow(r), or a circumflex(^) in the logicalname A logicalname
rnaybe enclosedin colons,(for example,:f0:),but lhe colon charactercannotbe Llsed
as part of the logicalname. If the logicalnameis to be usedas a prefix to a pathname,
it must be enclosedin colons. (Prefixesare discussed
in a lalcr sEclionof tn$
chapter.)

Leadingand embeddedhlanksare significant.For example,if the STRING usedto
definea logicalnamecontainsa leadingblank followedby two X's, the logicalnarneis
nol simply two X's. Ratherit is a blank followedby two X's.

The ExtendedI/O Systemdoesnot distinguishbetweenuppercaseand lowercase
lettersin logicalnames. For example,the ExtendedI/O Systemconsìdersrlz and
XYZ to be the samelogicalname.

3.6.2LogicalNamesandObjectDirectories
Every I/O job has three distincttt?es of objectdirectoriesin which objectscan be
cataloged.(The specificcharacteristics
oî an I/O job are describedin the nextsection.)
When looking up a logicalnamc,the ExrendedI/O Sysremsearchesthesedirectoriesìn
the order they are listedhere,and it stopswhen it finds the name. One effectofthis
searchschemeis that you can make a logicalnameavailableto only on€ job, to a group oI
jobs,or to alljobs in the system.
The objectdirectoriessearched,and the order h which they are searched,are
1.

The objectdirectoryof the locatjob. The localjob ìs the job containingrhe task rhat
requestedthe ExlendedI/O Systemto find the logicalname.
lfyou wish to sharea connectionwilh tasksin the samejob,but no! otherjobs,
catalogthe token for the connectionunder a logicalnamein the local object
orfecrory.

ExtendedI/O User'scuide

[.UNDAMENTAL CONCEPIS

The objectdirectoryof the globaljob. An I/O job's globaljob is that job whose
token is catalogedunder the nameRQGLOBAI in the objectdirectoryof the I/O
job. For example,if the RQGLOBAL entry in Job A's objactdirectoryis a token
for Jub B, Job B's objcct directoryis the globaldirecrory.
Ifyou wish to shareconnectionsamongtasksin severaljobs,designateone global
job. Then catalogtokensfor sharedconnectionsin the globaljob objectdirectory.

The objectdirectoryofthe rootjob. The rootjob is the firstjob createdwhenyorl:
systemis started, All otherjobs in the rystemare offspringofthe rootjob. The
rootjob objectdirectoryis availableto everyjob in the system.
Ifyou wish to sharecertainconnectionswith all tasksin the system,catalogtokens
for the connectionsin the rootjob's dilectory.

CAUTION
Before all I/O job exits, it must uncatalog any objects il cataloged ir olher

directories(globalor mot). If, for example,
a job catalogs
thetokenfor a
conn€ctionin the root job objectdirectorysnd then exits without
uncatalogingthe tok€n,the logicalnam€and token reúain eventhoùgh
the connectionis deleted.From then on, using the connecfionor referring
to the logical name\vill causean error,

3.7 r/o JOBS
Anyjob usingEfended l/O Systemcallsmust be an I/O job. I/O jobs can be created
both when the systemis initializcd,and whenprogramsare running. During
configuration,you definethe characteristics
of I/O jobs îhat are createdwhen the system
is initializecl.You useeither the CREATE$tO$JOBor RQE$CREATE$IO$JOBsystem
call to createjobs while the systemis runnìng. Both of thesesystemcallsperform the
sameoperations;the CREATE$IO$JOBsystemcall is compatiblewith iRMX I systems
and reseÍvesup to 1M byrefor rhejobs memorypool, and the ReE$CREATE$IO$JOB
systemcall givesyou the ability to reserveas much as lóM bytesfor the job's memory
pool. Both systemcalls are described in the Etteaded íRtrlX II ExtendedI/O SystemCaIs
RefercnceManual.
An l/O job (as opposedto a non-l/O job) must have

3-8

A globaljob. A token for the globaljob musrbe caralogedin the I/O job,soolecr
directoryunder the name RQGLOBAL, as explainedin the previoussection.

A defaultprefi{. The defìult prefix is a connectioncaraÌogedunder the nameg io
either the localjob objectdirectoryor the globaljob objectdirectory. Default prefixes
are discussedin the nexî sectionof this chapter.

Extended
I/O User'scuidc

FUNDAMENTALCONCEPTS

A defaultuserobject. l hisuserobjecrmustbe cataloged
in the I/O job'sobject
directoryunderthenameR?IOUSER.A defaultuserobiectis requled to access
namedfilesvia Exrended
I/O Systemcalls.Namedfilesind userohjectsare
thoroughly
discussed
in Chapter4 ofthis manual.

ROE$CREATE$IO$JOB
automarically
inirializes
the newjobwith a defaultuserobje,:jt,
globaljob,anddefaultprefix ('Automaticall/'meansrhatthesecharacteristics
of a new
l/O job arenot specified
with paramerers
in rheRQE$CREATE$IO$JOB
systemcali,
but are inheritedfrom theparentjob.Othercharacteristics
suchaspriorityandstacksize
canbe explicitlyspecified
parameters
as
in the RQE$CREATE$IO$JOB
call.)
Any taskthatinvokesthe RQE$CREATESIO$JOB
sysrem
callmustbe runningwithinan
I/O job. Thisrestrictionleadsto an obviousquestion.Howcanyoucreatethefirst I/O
job? You cancreateit duringrheconfiguration
ofyour applìcation
system.
Whileconfiguring
yourapplication
system(described
in Chapter7), youcanspecifyrhc
characteristics
ofone or mo.eI/O jobsthat arecreatedwhenthe systemis initialized.

3.8 PATH$PTR
PARAMETERS
AND DEFAULTPREFIXES
SomeExtendedI/O Systemcallsrefer to files rather than to connections.All suchcalls
require a path$ptrparameterto identili the tîe to be attached,created,or otherwise
manipulated.
The completeinterpretationof the path$ptrparameterdependsupon the kind of file
(named,physical,stream,or remote) beingmanipulated.Detailsabout this parameter
are discussedin Chapter4 (for namedand remotefiles), in Chapter5 (for physicalfiles),
and in Chapte.6 (for streamfiles).
However,one aspectof the pathgptrparameterappliesto all four kinds of files. If rhe
parameteris set to NIL, or if it points to a null STRING (an iRMX II STRING containing
zero characters),the Extendedl/O Sysremmanipulatesthe file indicatedby the default
prelt of lhe callingtask'sjob.
The defaultprefir is an attributeof an I/O job, and it is a connection(either a device
connectionor a file connection).It is catalogedunder the name$ in either the local or
the globalobjert directoryfor thejob. Whenevera task invokesa systemcall bur doesnol
specirya logicalname,the Extendedl/O Systemlooks up the defaultprefir and usesthe
associated
connection.

ErtcndedI/O User'scuide

4.1 OVERVIEW
Namedfilesareintendedfor usewith random-access,
secondary-storage
devices
suchas
diskdrives,diskettedrives,andbubblememories.Namedfilesprovideseveralfeatures
thatare not providedbyphysicalor streamfiles. Thesefeaturesinclude
r MultipleFileson a SingleVolume
r

HierarchicalNaming of Files

AccessControl

Thesefeaturescombineto make namedfiles extremelyusefulin systemssupportingmore
than one applicationand in applicationsthar require more than onc filc.
Named files can alsoresideon remotesy$tems.You accessremote naúed files in the
sameway you accesslocal namedfiles. To accessremote files,you must be usingthe
iRMX NetworkingSofnvare,which is availableseparatelyfrom the iRMX II Operatin-g
System.

4.2 MULTIPLE
FILESON A SINGLEVOLUME
As shownin Figure4-1,1,ourapplicationcan usenamedfiles to implementmore than one
file on a singìevolrrrne This can he very usefulin applicationsrequiringmore than one
operator.5uchas lrbn\action-fr,\.isingryslem\.

EÍended I/O Use/s Guide

,t-l

NA]\fED FILES

4.3 HIERARCHICAL
NAMINGOF FILES
The namedfiles featureallowsyour applicatjonto organizeits files into a number oftreelike structures,as depictedin Figure 4-1. Eachsuchstructure,calleda file tree, mustbe
containedon a singlevolume,and no two file treescan sharea volume. In other words,if
a volumecontainsany namedfiles,the volumecontainsexactlyone file treeEach file tree consistsoftwo categoriesoffiles-data files and directo.ies. Data files
(shownas trianglesin Figure 4-1) containthe informationthat your applìcation
rnanipulates,suchas inventories,accountspayable,transactions,text,sourcecode,or
objectcode. In contrast,directoryfiles (shownas rectangles)containonly pointersto
other files- The purposeof direcroryfiles is to giveyou flexibilityin organizingyour lile
T{) illustratethis flexibility,take a closelook at Figure 4-1. It showshownamed files can
be usefulin multi-usersystems.The figure is basedon a collectionof h)?othetical
engineerswho work lor three departments(Departments1, 2 and 3). Each engineeris
responsiblefor his own files.

4-2

Extended
l/O User'sGuide

NAMEDFILES

ligùre 4-1. Exampleofa NamedFile Tree

This multipersonorganizationis reflectedin the file tree. The uppermostdirectory
(calledthe volurDe'srrx)1directory)points to fhree "departmentdirealories."Each
departmentdirectorypoints îo several"engineer'sdirectories.',The engineerscan
organizetheir files as theywish by usingtheir own directories.
The root directoryof a remotedeviceis referred to as A virtual root. This is becausethe
remote systemselectsthe directoriesand files to be madeaccessible
over the OpenNET
network. Not all files and directorieson a remotesystemare automaticallyaccessible.
Each fìle (directoryor data) hasa uniqueshortestpaîh connectingit to the root diectory
of the volume. For instance,in f,igure4-1,the tile calledSIM-SOURCE hasthe path
DEPTl/BILL/SIM-SOURCE, wherethe slash(/) is usedro separarethe componenrsot
the path. This notion of "path"reflectsihe hierarchicalnature of lhe named-filelree.

ExtendedI/O Usefs Guide

4-3

NAMEDFILES

Arother characteristic
of hierarchical
file namingis thatthereis lesschancefor duplicate
file names.For example,
notethatFigure4-1containsdirectories
for two indiviouats
namedBill. (Thesedirecto.ies
areon theextremeleft andrightof the third levelof the
figure.)
Evenifthe rightmostBill hada datàfile with the file nameofSIM-OBJECT,its path
woulddifferfrom thatleftmostBill'sSIM-OBJECT.Specificaly,
rhelefrmostSIMOBJECTis identifiedby
DEFTl/BILL/SIM-OBJECI
whereasthe rightmostSIM-OBJECT
wouldbe identifiedby
DEPT3/BrLL/srM-OBJECT
Nowthatyouknowwhata namedfile is,let'slook at howthe tasksofyour application
tell
theExtendedI/O System
whichnamedfile to manipulate.

4.3.1 SystemCallsRequiringConnections
Onceyou havea file connectionfor a particularnamedfile, you can usea token for the
connectionas the connectionparameterin any of the followingsystemcallsto perform
I/O throughthe connection:

s$closE
S$DELETE$CONNECTION
S$GET$CONNECTION$STATUS
S$OPEN
$READ$MOVE
S$SEEK
S$SPECIAL
S$TRUNCATE
S$WRITE$MOVE
However,if lhe connection
wascreatedby a taskin a differentjob,yourtaskshouldnot
usethe contectionin anyoîthesesystemcalls.Rather,yourtaskshouldfirst obtaina
new conncction to the same file by pcrforming the following steps:

Catalogthe currentconnectionill the objectdirectoryof your task'sjob. Thls
establishes
a logicalnamefor the currentconnection.

Using the newly-definedlogicalname,invokethe S$ATTACH$FILE systemcall to
obtain anotherconnectionto the samefile. Your task can use this se€ond
connectionto invoke any of the systemcallslistedabove.

lfyour task doesattemptto usea connectioncreatedin anotherjob,the Extendedl/O
Systemwill relum an exceplioncoderather than performingthe requestedfunction.

Extended
I/O User'sCuide

NAMEDFII,ES

4.3.2SystemCallsRequiring
Paths
To useanyofthe followingsystemcalls,yourtasksmùstuscan Extended
I/O System
path,ratherthana connection,
ro tell theEfended I/O System
whichfile vouwishto
manipulate:
S$ATTACH$FILE
S$CIIANGE$ACCESS
S$CREATE$DIRECTORY
S$CREATE$FILE
S$DELETE$FILE
S$GET$DIRECTORY$ENTRY
S$GET$FILE$STATUS
S$GET$PATI
I$COMPONENT
S$RENAME$FILE
For namedfiles, an ExtendedI/O Syslempath hasrwo componenrs.The first componenr$
calleda prefi{, and the secondis calledthe subpath.Let's etamine thesecomponenrsone ar a
lime.

4.3.2.1Prefixes
A prefix is a logicalnamefor n connectionto either a device,a nameddirectoryfile, or a
nameddata file. The devicemay be either a local or remoredevice. The files may alsobe
either local or remotefiles. The purposeof the prefix is to tell the ExtendedI/O Sysrem
whereto begininterpretingthe subpath.The prefir is the only componentrhat is ùsedto
distinguisha local connectionfrom a remoteconnection.Let's look at eachof the
possibleinterpretationsthat the ExtendedI/O Systemcan derivefrom a prefir:
.

If the prgfiLi! aiolledian to a local device,the ExtendedI/o systembegins
scanningthe sùbpathat the root directoryof the device.

If the plg|i2lj8le!4gdjprIa4
rcloo e device, the Extended I/O Sysrembegins
scanningthe subpathat thè vìrtuàI root dircctoryofrhe device.

If the prefix is a connectionto a local or remotenameddirectoryfile, the Extended
l/O Systembeginsscanningthe subpathat the specilìeddirectory.

If the prefix is a colqectien to a local or remotenameddata file, the ExtendedI/O
Systemchecksto seeif the subpathis nul!. If it is, the ExtendedI/O Syst€m
manipulatesthe file indicatedby the prefix. If the subpathis not null, the Extended
l/O Systemreturnsan exceptioncodejndicatingthat your applicationprogram is
attemptingto usea data file as rhoughit were a directoryfile.

All other syntaxapplìesto both local and remotefiles. For more information on remote
files, see thc r'llMx Networkiùt Sofhrare Llset'sGuide.

ExtendedI/O Usedscuide

4-5

NAMEDFILES

4.3.2.2SubDaths
A sùbpathis a data-filenameor a sequence
ofdirectorynamesoptionallyiollowedby a
datafile name.For instancc,
referringto Figure4-1,TOM/TEST-DATA/BATCH,1is a
subpaththatleadsfrom theDEPTl directoryto the datafile namedBATCH-1.
Anotherexamplefrom thesamefigureis TOM,whichis a sìrbpath
thatleadsfrom the
directorynamedDEPT1to the directorynamedTOM.
4.3.2.3 UsingPrelixesin ConjunctionWith Subpaths
Thetasksofyour application
systemcanusea prefixin conjunction
with a subpathto
createa mmpletopathfor a namedfile. Theprefixgenerally
refersto a di.ectory,aod
the subpathgenerally
refersto a directoryor datafile that is a descendant
of the directory
indicrìted
bytheprefix
4.3.2.4SpecifyingPathsin SystemCalls
Thosesystemcallsthatrequirepathshavea path$ptrparameter.Thetasksofyour
applìcation
systemcanusethispath$ptrparameter,
alongwith the defaultprefix,to
specilythe file to be manipulated.
4.3.2.5 PathSyntax
Whenyourapplication
tasksinvokea systemcallthatrequiresa path,thetasksmust
providea path$ptrparameter.Whendealingwith namedfiles,thisparameteris a
POINTERto a STRING(seeAppendixA for a definitionof STRING)thatmustbein
oneof thefollowingfour forms:
. NULL STRING
lf the STRINCis zerocharacters
long,theExtcndedI/O Sysrem
will acton rhefile
indicatedby the defaultprefixof thecallingrask'sjob.
.

LOclcAI NAME ONLY
If theSTRINGconsists
onlyof a logiadnameenclosed
in colons,rheExtended
I/O
Systemwill lookup thelogicalnameandobtaintheassociated
connection.Then,
because
thesubpathis empty,the Extended
I/O System
will acton thedatafile or
directoryfile indicatedby theconnection.

4-6

Extended
I/O Usefs cuide

NAMEDFILES

SUBPATH ONLY
The STzuNGcanconsistof a subpath
withouta prefix. TheExtended
I/O System
interpretssuchsubpaths
by startingat rhedirectoryindicaredby the defaultprelixof
thecalljngtask'sjob. Thenthe Extended
I/O Systemfollowsrhesubpathfrom
directoryto directoryuntil it reaches
thefinalcomponent
of thesubpath.Thisfinal
component
is thefile on whichtheExtended
I/O Systemacts.
Be awarethatwhenever
the STzuNGcontainsa subpathwithouta logicalname,the
defaultprefixmustbe a logicalnamefor a connection
to a deviceor to a named
directoryfile. If, ìnstead,
the defaultprefixrepresents
a connection
to a nameddata
file, the Extended
I/O Systemreturnsan exception
codeindicatingthatyourtaskis
attempting
b usea datafile asa directory.
The followingsubpathis an exampleof themostcommonform:
^/B/c/D
wh€reA, B, andC arethenamesof directoryfiles,andD is the nameof eithera
directoryor datafile. Thisexampìe
causes
theExtendedI/O Systemto startat the
defaulldirectoryanddescend
to DirectoriesA, B, andC in order. 'l'henìt actson l).
An exampleof a lesscommonform ofsubpathis
'|A/B/C/D
wherethe up-arrow(î) or circumflex(^) tellsthe hxtendedl/O Systemto ascendone
levelin the hìerarchy
offiles. In otherwords,rheExrended
I/O System
wouldread
thisexampleasr "Startwith thedirectoryindicatedby the defaulrprcfixanclascencl
to
its parent.Thendescend
to directories
A, B, andC in order.Thenacton FileD.
'lhe
Extended
I/O System
canalsoac4eptconsecutive
up-arrows.For example
^^AlBlc
wouldcausethe Extended
I/O Systemto startwiththe directoryindicatedby the
defaultprefixandascend
twolevelsbeforeinterpretingtheremainderof thesubpath.
Anotherpossibility
is for thesubparh
to beginwith a slash(/). For example
/AlB/C
Whenever the Extended I/O Systemdetects a slash at the beginning of a subpath, the
Extended I/O System will start inrerpreting the remainder of the subpath at the root
directory of the device indicated by the prefix

Extended
I/O User'sGuide

NÀMED FILES

LOGICAL NAME FOLLOWEDBY SUBPATI]
Your application
codecanusea STRINGconsisting
of a logicalname(enclosed
in
colons)followedimmediately
by a subpath.For example
:F0:A/B/C/D
The Extended
I/O Systeminterpretsthisexampleasfollows.First,it looksup the
logicalnameF0 in the objectdirectoryof thelocaljob,or if necessary,
theglobalor
rootjob. Thenit followsthe subpathfrom the directoryassociated
with the
connection.Soin theexample,
theExtended
I/O System
wouldfind the directory
associated
with F0,andit wouldsreprhroughDirectoriesA, B, andC. Finally,the
ErtendedI/O Systemwouldacton File D.

4.4 CONTROLLING
ACCESSTO FILES
ln most envionmentswherefiles are sharedamongmultiple users,it is necessaryto have
a meansof conttollingwhich usershaveaccessto which files. And amonguserswho have
accessto a givenfile, it is frequentlynecessaryto grant different kinds of accessto
different users.The iRMX ll OperatingSystemprovidesthis control by identilyingusers
with user lDs and by embeddingaccessrightsior theselDs into the files. This section
describesthe userID ald filc acccssmechanisms.

4.4.1 UsersandUserObiects
The iRMX II Opefatltg Systemusesthe conceptof "user"!o coúelate file accessto
peopleor to jobs. But the precisedefinition of "user',dependson the nature of your
application.
Ifyour applicationallowsa smallg.oup ofpeople to enter information (at rerminals.for
example),you might want to considereachperson(or smallgroup ofpersons)a use..
This allowseachindividual(or smallgroup) to maintainaccessdifferent from othe.
individuals(or smallgroups).
Alternatively,ifyour applicationdoesnot interactwith people(or allowsonly one person
to interact),you might wish to considereachiRMX II job as a user. This setrjpwould
allowyour applicationto control the files that €achjob can access.
In more generalterms,the set of entitiesthat manipulatenamedfiles in your systemis
the set of all users. Ifyou want all ofthese entitiesto be ableto accessany file, you can
considerthem to be a singleuser. However,ifyou want to distributediîferent accessto
diff€.ent collectionsof theseentities,you must divide the entitiesinto subsets,eachof
which is a separateùser.

4-8

Extended
I/O Uset'scuidc

NAMEDFILES

For example,lookat Figure 4-1. As mentionedearlier,all engineersare.esponsiblefor
their own files. If engineerswant to haveuniqueaccessto their files (perhapspermitting
no one elseto usc th€ir files),eachengineermus! be a separateuser. However,if all
engineersare willing to úe uniform accessto othe. membersofthe department,then the
departmcnîcan be a s€parateuser,

4.4.1.1UserlDs
A userlD is a 16-bitnumberthatrepresents
anyindividualor collectionofindividuals
reqùi.inga separate
identityfo. thepu.poseofgainingaccess
to files.
4.4.1.2UserObiects
TheExtendedI/O Systemusesa special[pe of obj€ctcalleda userobjectwhcn
determining
access
rightsto files.A userobjectcontainsa list of oneor moreuserIDs.
joh
EachT/O
hasa defaultùserobjectwhichdefinesthe access
rightsfor all tasksin that
I/O job. Whena taskin an I/O job attemptsto manipulate
a file,the OperatingSysrem
computes
aocess
bycomparing
the userIDs listedin the defaultuserobjectwith
informationcontained
in rhefile itseli
lo understand
userobjects,
consideran application
in whicheverypersonwhoaccesses
thesystemhasa separate
I/O job andthereforea separate
userobject.The userobject
represents
theperson.
The first ID in the user object is the owner lD. This is the ID of the user whom the objesl
represents. Ifyou think of a user object as a person, the owner [D represents the name oî
that person. When a person creates fiLes,the Operating System auîomàtically embeds rhe

owner ID of that person'suserobjectinto the file, allowingthat personautomaticaccess
to the file.
The IDs that follow the ownerID representadditionalkinds of accessthat the personhas.
For example,peopleoften belongto organizaîionssuchas athleticclubsand traternal
groupswhich distributeidentitycardsto their members.To participatein the
organization,peoplemust showtheir idendrycards!o prove they are members.The user
lDs that follow the owner ID servethe samepurpose. They identifythe personas on€ of
a selectgIoup, all ofwhom havcthc sameaccessto a certainset of files.
4.4,1.3 DefaultLJserObjectfor a Job
All I/O operationsperformedwithin a singlel/O job are performedon behalfof one user
objet, which is calledthe defaultuserobject. The ExtendedI/O Systemassumesthat the
userobjectcatalogedin the I/O.iob's objectdirectoryunder the name R?IOUSER is the
defaultuserobjectfor that I/O job.

ExtendedI/O Ilser's Cùide

4-9

NAMED FILES

Dudng the configurationofthe ExtendedI/O System,you set up the defaultuserobjects
for your initial I/O jobs (the onesthat start runningimmediatelyupon system
initialization). I-ater,when a task createsan I/O job (via the RQE$CREATE$IO$JOB
sysremcall),the new I/O job inheritsthe defaultuserobjectofits parent I/O job. That is,
the ExtendedI/O Systemautomaticallycatalogsthe parentjob'sùser objectin the new
I/O job's objectdirectoryunder the rarùe R?IOUSER- In rhisway,rJefaultuserobjects
passfrom parentjobs to offspring.
To preventproblems,you shouldconsiderR?IOUSER to be a reservednameand avoid
usingit.

4.4.1.4Supporting
Dynamic
LogonandiRMX.NET
In a systemthat supportsthe dynamiclogon facilitiesofthe Human lnterface or iRMXNET, a uscr dcfinition file (UDF) liststhe user name,password(in encryptedform), usef
ID, and other informationabout everyonewho is allowedto log onto the iRMX II system.
The ExtendedI/O Systemprovidesîhe GET$USER$IDSsystemcall so that you can look
ùp the permitted userID of any userwhoseusernameyou know. This systemcall is
usefulfor tasksthat needto set up userobjectsbasedon the informationlist€d in the
UDF,
The ExtendedI/O Systemalsohelpscontrol remotefile accessthroughthe sysremcall
VERIFY$USER. This systemcall validatesusernamesand passwordsto ensurefile
secud[y. As a aesult,the ExtendedI/O Systemallowsuserswho log onto dynamiclogon
terminalscontrolledby the Human Interfaceto accessremotefiles.

4.4.2Typesof Accessto Files
Each of the two kinds of namedfiles-directoryfiles and data files-can be accessed
in four
differentways.
Every directoryfile can potentiallybe accessed
in one or more of the followingways:

Delete

Deletethe diredoryfile with S$DELETE$FILE
or renamethe
dire€toryfile witl S$RENAME$FILE.

List

Obtainthecontentsofthe direcroryfile wirhS$READ$MOVE.

Add Entry

Add entriesto the directorywithS$CREATE$FILE,
S$CREATE$DIRECTORY,
or S$RENAME$FIT.F-.

ChangeEntry

Changetheaa:essrightsof fileslistedin the directorywith
S$CI{ANGE$ACCESS.

Every data file can potentiallybe accessed
in one or more of the followingways:
Delete

,t-10

Delete the file with S$DELETE$FILE or renamerhe file wlrn
S$RENAMESFILE.

Extended
I/O Use/s Guid€

NAMEDFILES

Read

Readth€ file with S$READ$MoVE.

Append

Add informationto the endof the file with S$WzuTE$MOVE.

Update

Changeinformationin the file with S$WRITE$MOVE
or drop
informationwithS$TRUNCATE$FIT.E.

A user'saccessrìghtsto a particularfile dependon the accesslist associated
with that file.
Accessrights to remotefiles are slightlydifferent than for namedfiles. For more
information on acaessrights to remote files, see the .RMX Networking SofrwareUser't
Guide.

4.4.3 FileAccessList
For eachnamedfile (data or directory),the OperatingSyst€mmaintainsan accesslrst
which definesthe userswho haveaccessand their ac,;ess
rights. Each acr-css
list is a
collectionof up to three orderedpairs havingthe form
lD, accessmask
The ID portion is a userID. The list of user IDs definesthe userswho can accessthe lle.
The accessmaskportion definesthe kind of file accessthat the correspondinguser has.
An accessmaskis a byte in which individualbits representthe variouskindsof access
permittedor deniedthat user. When sucha ìrit is s€t to 1, it sigîifi€s that the associat€d
kind of accessis permitted. Wlen set to 0, the bit signifiesthat the associatedkind of
accessis denied.
iRMX-NET usesa slightlydifferent accessmaskfor remotefiles than is usedfor local
files.
'lhe

associationbetweenthe bits of the accessmaskand the kinds of accessthey controì
are as follows(wherebit 0 is rhe least-signiîicant
bit):
Bl

DirectoryFiles

Data Files

0
I
2
3

Delete
List
Add Entry
ChangeEntry

Delete
Read
Append
Update

The remainingbits in the accessmaskhaveno significance.

Extended
I/O Uset'sGuide

4-11

NAMED FILES

For example,an accesslist for a datafile might look like the following:
5B31 00001110
9F2C 00000010
wherethe Tl) numbers(left colùmn)are in hs€decimal and the accessmasks(right
column) are in binary. This meansthat the ID number5831 has read,append,and
updateaccessrights,while the ID number9F2C hasrhe read ac.essright.
The first entry in the file's accesslist is placedthere automaticallyby the E\tended I/O
Systemwhen it createsthe file. I he lD portion of that entry is the tirst ID number in the
defaultuser objectofthe callingtask'sI/O job, That lD is known as the ownerID for the
tile. The Extendedl/O Systemfills our lhe aocessrighrsporlion !o granrlhe ownerID
full (unlimited) accessto the file.
Taskscan alter the accesslist of a file by meansof the S$CHANGE$ACCESSsystemcall.
With S$CI{ANGE$ACCESS,you can add or deleteTl)-access
pairs,and you can c.hange
the accessriqhts ofIDs alreadyin the accesslist.

NOTE
The userwhoseID is the ownerID for a file hasone advantageover other
users. Other than the systemmanageruser(describedlater), only a file's
ownercan usethe S$CHANCE$ACCESSsystemcall to modiry the file,s
accesslist without beinggrantedexplicitpermissionto do so.

4.4.4 Computing Access for File Connectíons
'Whenever
a taskcallsS$CREATE$DIRECTORY,S$CREATE$FILE,or
S$ATTACH$FILE, the ExtendedI/O Systemconstructsan accessmaskand binds it to
the file connectionobjectreturnedby the call. This acrcess
maskis constantfor the life of
the connection,evenif the accesslist for the tjle is subsequently
altered. When the
connectionis usedto manipulatethe file, the accessmaskfor the connectiondetermines
how the file can be accessed.For example,if the computedaccessrightslbr a connection
to a data file do not includeappendingor updating,then that connectioncannotbe used
in an invocationof S$WzuTl$MOVE.
When a taskcallsS$CREATE$DIRECTORYor S$CREATE$FILE,the ExrendedI/O
Systemsuppliesan accessmaskthat grantsfull accessto the connection.However,when
a task callsA$ATTACH$FILE, the ExtendedI/O Systemcomparesthe defaultuser
objectwith the file's accesslist and computesan aggregatemask.

4.12

Extended
I/O Use/s Guide

NAMEDFILES

Figure4-2illustrates
the algorithmthatthe Exrended
I/O Systemusesduringa callto
S$ATTACH$FILE.As thefigureshows,
the OperatingSystem
compares
the lDs in rhe
default user object with the IDs Ìn thc filc's acccsslist. The accessmasks correspondìng to
matching IDs are logically ORed, forming an aggregatemask.

- ?'..i:3,i"1+Í."^î

Figùre 4-2. Cr|mnutinBlhe {cce(\ l\lAskfirr a File Connection

NormalÌy,the Extendedl/O Systemusesthe aggregateaccessmaskembeddedin the
connectionto determinea task'sability to accessa file. However.there are two
circumstances
in which the Extendedl/O Systemcomputesaccessagain: during
S$CHANGE$ACCESSand during S$DELETE$FILE. when a task invokesone of rhese
systemcalls,the ExtendedI/O Systemcomputesthe accessro rhe rargerfile. If the
default userobjectdoesnot haveappropriateaccessrights,the ExtendedI/O System
deniesthe task the ability to deletethe file or changethe access.

ExtendedI/O User'sGuide

4-13

NAMEDFILES

NOTE
When computingaccess,
the ExtendedI/O Systemchecksthe accessonly
to the last file in the specifiedpathnàmeand to the par€nt directoryof the
last file. It doesnot checkthe accessto any other dhectoryfiles specified
in the pathname. If the pathnameis null, the Extendedf/O Systemchecks
the accessto the file indicatedbv the defaultorefix.

4.4.5SpecialUsers
There are two userIDs that can havespecialmeaningto the ExtendedI/O System.One
is the number0 (the systemmanageruser) and the other is the numberoFFFFH (the
WORLD user).
4.4.5.1 Sysiem ManagerUser
If so indicatedduring the configurationprocess,userID 0 representsthe 'system
manager,rr
or 'rsuperuser." A userobjectcontainingthis valueis privilegedin two
respects.First, when it is usedto createor attachfiles.the resultingfile connection
automaticallyhasread accessto datafiles and list aclessto directoryfiles. This is true
evenif a file's accesslist doesnot containan ID-accessmaskpair whoselD value is 0.
The secondprivilegegrantedsucha userohjecris that ir can aall S$CIIANGE$ACCESS
to changeany file's accesslist.

4.4.5.2WorldUser
By convention,the user ID 0FFFFH representsWORLD (all usersin the system).To
implementthis convention.you shouldplacerhe ID for WORLD in the list of userTDsfor
the initial userobjects]'ou set up during the conîigurationof the ExtendedI/O System.
Then,whenyour initial l/O jobs createnew I/O jobs, rhe default userobjectsthey inherit
will containthe WORLD ID.
By implementingthe WORLD convention,your appÌicationcan set asidecertain files as
public iiles, givingeveryonelimited access.For example,your file systemmight containa
scriesof utilities,suchas compilersor linkers,which all uscrsneed to access.Insteadof
grantingeveryoneaccesson an individualbasis(whichis impossibleifyou havernore than
three use.s),you cxn granî the userWORLD sclessto the files. SinceWORLD is on thc
lD list of everyuser object,this grantseveryoneaccessto the files.
As a side effect of includingthe WORLD ID in everyuserobject,any file whoseownerID
is oFFFFH (WORLD) can haveirs accesslist modilìedby anyone.That is, any file
connectìonfor that file can be usedin a call to S$CHANGESACCESS.

4-r,t

Extended
I/O UseCsGuide

NAMEDFILES

4.s EXTENDED
r/O SYSTEM
CALLSFORNAMEDFTLES
The Efiended I/O Syslemprovidesa numberof systemcallsthat relate to namedfiles.
The followingsectionsbriefly explainthe purposeof eachof thesesystemcalls. The brief
descriptionsare groupedby fulction rather than alphabetically.T\e Extentled\RMX II
ExtendedI/O Sytem Calk RefermceManual containscompletedescrìptionsof the
Extendedl/O Systemcalls.

4.5.1 Obtainingand DeletingConnections
The ExtendedI/O Systemprovidessevensystcmcallsthar rclarc to obrainingans
deletingconnections.
.

S$CREATE$FILE. This call applìesonly to data files. Your applicationsoftware
must usethis call to createa new datafile. When an applicationtask invokesthis call,
the Ext€ndedI/O Systeù autonÌiilìcallyaddsan €ntry jn rhe par€nt directorylor this
new fiÌe.

S$CRIATE$DI RECTORY. This call appliesonly to directoryfiles. When your
applicationsoftwareneedsto createa dire.tory, the softwaremust usethis system
call. The call cannotbe usedto obtaina connectionto an existingd ectory. The
ExtendedI/O Systemautomaticallyaddsan entry in the parent directoryfor this neu
orIectory.

S$ATTACH$FILE. This call îpplies to both data and directoryfiles. Your
application!askscan uselbis call to obtaina connectionto an existingdata file or
directory.

S$DELETE$CONNECTIoN. This call appliesto both data and dire.tory files. Your
applicationtaskscan usethis call to deletea connectionto either kind of namedfile.
This call cannotbe usedto deletea deviceconnection.

LOGICALI$ATTACH$DEVICE. This call doesnot directlyapplyto either data or
directoryfiles. Your applicationsoftwareusesthis call to obtain a connectiorìto a
local or remoîe deviceand to catalogthe logicalnamefor the devicein the object
directoryof the root job. Even thoughthis connectionìs a deviceconnection,it can be
usedas the prefix (logicalname)for the root directoryof the device.

LOGICAI$DETACH$DEVICE. This call doesnot directlyapply to either data or
directoryfiles. Your applicationsoftwareusesthis call to deletea connectionto a
deviceand removethe Ìogicalnameof the devicefrom the objectdirectoryof the root
Joo.

HYBRID$DETACH$DEVICE. This call is similar to
LOGTCAI^$DETACH$DEVICEin that it deletesa connectionto a device. However.
HYBRID$DETACH$DEVICE doesnot removethe device'sÌogicalnamefrom the
objectdirectoryof the root.job. Your appljcationsoftwareusesthis call when it wants
to temoorarilvattacha devicein a different manner.

Extended I/O Usefs Guid€

4-15

NAMEI) FILES

4.5.2Manipulating
Data
Six systemcallsallow tasksto manipulatethe data in a file. All six can be usedwith data
files,while only four applyto directoryfiles. The systemcaÌlsare
.

S$OPEN. This call appliesto both data and directoryfiles. Beforeyour application
softwarecan useany olher systemcallsto manipulatefile data,the softwaremust
open a connectionto the file. This systemcall is the only way to open a conne4tion-

S$CLOSE. This call appliesto both data and directoryfiles. After your application
softwarehasfinishedmanipulatinga file, the applicatjoncan usethis systemcall to
cìosethe file connection.Your applicationcan electto leavethe file open,letting the
ExtendedI/O Systemcloseit whenthe connectionis deleted,but closinga file
releasesmemoryresourcesassociated
with the connection.

S$SEEK. This systemcall appliesto both data and directoryfiles,and works the saúe
on both file t)?es. Wheneveryour applicationsoftwarereads,writes,or truncatesa
file, the r€questedaction takesplaceftt the locationspecifiedby the connection'sfile
pointer. The applicatìoncan tell the Extendedt/O Systemwherethe operationis ro
take place. To do this,your applicationtask usesthe S$SEEKsystemcall to position
the file pointer of the file connection.The S$SEEKsystemcall requiresthat the file
conneclronoe open,

S$READ$MOVE. This systemcall appliesto both data and directoryfiles. Your
applicationtaskscan usethis systemcall to read file data from the locationindicated
by the fiìe pointer into a segmentof memor].
Before usingthis systemcall,your appÌicationsoftwarecan usethe S$SEEKsystem
callto positionthe file pointer. The S$READ$MOVE systemcall requiresthat the
file connectionbe open. Also, the segmentof memorythat receivesthe information
from the file must havewrite access,
becausethe systemcallwrites the information
from the file to memory.

S$WRITE$MOVE. This systemcall appliesonly to data files. Your application
softwarecan usethis systemcall to transfernew informationfrom a segmentof
memoryto the file. Before usingthis call, an applicationtask can useS$SEEKto
positionthe file pointer to the locationwithìn the file to receivethe informatìon.
The S$WRITE$MOVE systemcall requiresthat the file connectjonbe open. Also,
the segmentof memoryoriginallycontainingthe informationmust haveread access,
becausethe systemcall readsthe informationfrom memoryand writes it to the fite.

4-16

S$TRUNCATE$FILE. This systemcall appliesonly to data files. Your application
softwarecan usethis call to trim informationfrom the end of the file. To do so.the
applicationt.rskfirst can useS$SEEKro positionthe file poinrer to thc first bytc to bc
dropped. Then îhe applicationinvokesthe S$TRUNCATE$FILE call to drop all
bytesat or beyondthe file pointer. The S$TRIJNCATE$FILEsystemcall requires
that the file connectionbe open.

ExtendedI/O Uset's Cuide

NAMEDFII,ES

4.5.3ObtainingStatus
There are three status-relaledsystemcalls,one for connections,one for files,and one ior
devices.The callsare S$cET$FILE$STATUS,S$cET$CONNECTION$STATUS.and
GET$LOGICAL,l$DEVICE$STATUS.The first two callscan be usedwirh Llalaànd
directoryfiles. The third call retrievesiniormationabout devices.

4.5.4 Deleting
and Renaming
Files
TheExtendedI/O System
providesonesystemcallfo. deletingfiles,andanotherfor
renamìng fiÌes. Each of these calls can be used with data and direcîory files. Thc calls arc

S$DELETE$FILE. Your applicationtaskscan usethis systemcall to deletedata and
directoryfiles. However,any atlempt ro deletea directorythat is not emptywill result
in an exceptionalcondition.

S$RENAME$FILE. Your applicationtaskscan usethis systemcall to renameboth
data and directoryfiles- In renaminga file, an applicaîiontaskcan move the file to
any directoryin the samenamedfile tree. For example,you can renameA/B/C to be
A/X/C. In efiect,this examplesimplymovesFile C from Directory B to Directory X.
This meansthat the applicationtaskcan changeeverycomponentof a file's path
nameexceptthe root directory.

4.5.5ChangingAccess
The ExtendedI/O Systemprovidesone systemcall to let the tasksofyour applicatiorì
changca filc's acccsslist. This call is S$CIIANCtr$ACCISS, and it appliesro boih d.ìr.ì
files and directories.One rule governsthe useof S$CHANCE$ACCESS-onlythe owrer
of a file or a userwith changeentry accessto the directorycontainingthe fiìe can change
the file's accesslist.

4.5.6 Deleting
Connections
The Extendedl/O Systemprovidesone systemcall to deleteconnectionsto files. This is
the S$DELETE$CONNECTIONsystemcall.

4.5.7 UsingLogicalNames
The Extendedl/O Systemprovidesthree systemcílls that relateto logicalnames. AlÌ
three oî these systemcalls are discussedin detatl infhe Exlended|RMX Il ExtentedI/O
SlstemCalL,ReferenceMa Ltal.
.

S$CATALOG$CONNECTION. This systemcall allowsyour applicationtasksto
createa logicalnameby cataloginga connectionin the objectdirectoryof ajob.

Extended I/O User's Guide

N \\4[D FILES

S$LOOKUP$CONNECTION. This systemcall acceptsa logicalnamefrom an
applicationtask,looksup the namein the objectdirectoriesofthe local,gobal, and
root jobs (in that sequence),and returnsa token for the first connectionfound. In
other words,this is the systemcall that your applicationsoftwareusesto equatea
logicalnameto a connectjon.

S$UNCATALOG$CONNECTION. This systemcall allowsyour applicationsoftware
to deletea logicalnamefrom the objectdirectoryof ajob.

4.5.8 Creatingand Deletingl/O Jobs
The ExtendedI/O Systemprovidesfour systemcallsthat relateto the creationand
deletionofI/O jobs.
.

CREATE$IO$JOB. Th;s systemcrll createsan I/O job while the systemis running.
(You can alsocreateone or more I/O jobs when the systemis configured,so that they
existwhen the systemstartsrunning.) This systemcall is availablefor compatibility
with the iRMX I OperatingSystem.Iî you usethìs systemcall to createI/O jobs,the
memorypoolsassociated
with thoseI/O jobs cannotexceed1 megabyte.

RQE$CREATE$IO$JOB.This systemcall isjust like CREATE$IO$JOB,exceptthat
it permitsyou to assignmemorypoolsof up to 16megabytesin sìze. It is
recommendedthat you usethis systemcall (insreadof CREATE$IO$JOB)for all new
applications,becauseit takesfull advantageof the iRMX Il features.

START$IO$JOB. This call alloìrsyou to start the inirial rask in an I/O job. When
you ì.lseCREATE$TO$JOB,you specil, either that you want the inìtial task to start
runningautomatically,or that you want to wait until issujngSTART$IO$JOB.

EXIT$IO$JOB. This systemcall providesyour applicationraskswirh a sonvenienr
methodfor terminatingan l/O job and informing the parentjob of the termination.

4.5.9 Performing
Miscellaneous
Functions
The ExtendedI/O Systemprovidesthree systemcallsto perform miscellaneous
operationsthàt do not fit into any other category.The callsare
.

S$SPECIAL. Your applicationtaskscan usethis systemcall to perform functionsthat
are peculiar to a particulardevice. Formatlìnga disk is an exampleof sucha function.
For more information,refer to the S$SPECIALsectionof the EtrendedíRMX II
ExtendedI/O SrstemQtlls ReferenceManuat.

S$GET$DIRECTORY$ENTRY. Your applicationtaskscan usethis systemcall ro
look up the nameof any file in a directory. This is the synchronous
versionof the
A$GET$DIRECIORY$ENTRY systemcall providedby the BasicI/O System.

4-18

ExtendedI/O Use/s Guide

NAMEDFILES

S$GET$PATH$COMPONENT.
Your application
taskscanusethissystemcallto
look up the nameof a file asit is knownin thefile,sparentdirectory.Thisis the
synchronous
versionof theA$GET$PATTI$COMPONENT
systemcallprovidedby
theBasicI/O System.

4.6 BASTCt/O AND NUCLEUSSYSTEMCALLS
Although the purposeof this manualis to describethe Extendedl/O System,several
systemcallsprovidedby the BasicI/O Systemand by the Nucleuswarrant mentionhere.
Thesecallsallow you to specificallymanipulateuserobjectsand prefix obje,cts.
The defaultuserand defaultprefir for eachI/O job a.e catalogedin thejob,s object
directory,and ùsersof the ExîendedI/O Systemdo not noÍmallymanipulatethem.
Before usingthe followingsystemcallsto alter theseobjects,refer to AppendixD of thìs
.

SET$DEFAULT$PREFIX (BasicI/O Sysrem)

o GET$DEFAULT$PREFIX (BasicI/O System)
.

CRDATE$USER (Bas;cI/O Systelt

DELETE$USER (BasicI/O Sysrem)

INSPEC' USER (Basicl/O Systern)

SET$DLFAULT$USER (BasicI/O Systent

GET$DEFAULT$USER (BasicI/O System)

CATAIOG$OBJECTlNucleusl

UNCATALOG$OBJECT (Nuctcus)

LOOKUP$OBJECT(Nucleus)

Reîet to lhe ExtendedíRMX II Batic I/O StstemCalh ReferenceManual andExtended.
iRlrIX II NucleusSysremCalL RekrenceMarual for complere informarion on using these
calls.

4.7 CHRONOLOGICAL
OVERVIEW
OFNAMEDFILES
Although many systemcallscan be usedwith namedfiles,thesesystemcallsmust be used
in a logicalsequence.
Figure 4-3 showsthe chronologicalrclationshipsb€lwc€nthc mosl frcqucntly uscdI/O
Systemcalls. To usethe figure,sta.t with the leftmostbox and follow the arrows. Any
path that you can trace is a legitimatcacqucnccof systcmcalÌs. This figurc is not a
completerepresentationof all possiblesystemcall sequences.

ExtendedI/O User'sGùide

4t9

NAMED FILES

DATA FILES
DIF ECTO RIES

[-l-{
FfF

-_l
|

oElfE

t"lt"-"'t

Figure 4-3. Chmnolog/ of FrequentlyUsedSystemCalls for NamedFiles

4-21)

Exfendedl/O Us€r'sGuidc

s.l oVERVIEW
TheiRMX II Extended
providesphysical
I/O System
filesto allowyourapplicatìons
to
read(or write) stringsof bytesfrom (or to) a device.In otherwords,a physicalfile
occupies
an entiredevice(or thedevice's
entirevolume),andthe Extended
I/O System
providesyourappiications
with the abilityto access
thedriverofthe devicedirectly.

5.2 SITUATIONS
REQUIRING
PHYSICAL
FILES
The closerelationshipbetweena deviceand a physicalfile is particularlyusefulwhen your
applicationsystemusessequentialdevices.For example,you shouldusephysicalfiles to
communicatewith ljne printers,displaytubes,plotters,and magnetictape uoits.
There are evensomeinstanceswhereyou shouldusephysicalfiles to communicate\À,ìth
random devicessuchas disk drives,diskettedrives,and bubblememories. For instance
.

FormattingVolumes
Whencvcryou crcatc an applicationtask to format a disk or diskette,the task must
haveaccessto everybyte on the volume. Only physicalfiles provide this kind of

Using Volumesin FormatsRequiredby Other Systems
lfyour applicationtasksmustread or write volumesthat havebeenformattedfor
systemsother than the iRMX II OperatingSystem,you must usephysicalfiles. Your
taskswiìl haveto interpret informationsuchas labelsand file strùctures,but a physical
file can provideyour taskswilh àccessto the raw information.

ImplementingYour Own File Format
Sùpposethat your applicationsystemrequiresa lesssophisticatedfile structurethan
that providedby iRMX II namedfiles. YoÙ canbuild a customfile structùreusingr
ohvsicalfile as a foun,-lation.

ExtendedI/O User'sGuide

PHYSICAL FILES

FILES
5.3 CONNECTIONS
ANDPHYSICAL
Although there is a one-to-onecorrespondence
betweenthe b,'teson a deviceand the
bytesof a physicalfile, the deviceconnectionis different from the file connection.The
ExtendedI/O Systemmaintainsthis distiÌrctionto remainconsistentwith namedfiles and
slrcàm files.This consislencyhelpsyou developapplicationsthat can useany kind offile.

5.4 SUGGESTION
FORMAINTAINING
FILEINDEPENDENCE
lfyou would like the tasksofyour applicationto be able to use streamor namedfiles in
addition to physicalfiles,you shouldseparatethe creationofthe connectionfrom the use
ofthe connection.For instance,if your applicationperfo.ms I/O to a file, you should
considerusingtwo distincttasksrather than one. The first task would be responsiblefor
obaaininga connectionto the file, and the second!askwould usethe connectionto
perform I/O. By maintainingthis separation,you can designthe secondtask to work with
any kind of filc.
lfyou chooseto usethis two-taskapproach,be surethat both tasksare in the samejob.
This will eliminatethe difficultiesassociated
with passinga file connectionfrom onejob
to another.

5.5 USINGPHYSICAL
FILES
Severalsystemcallscan be usedwith physicalfiles,however,the order in which thcy arc
usedis not arbitrary. The followinglist providesa brief description(in chronological
order) ofwhat an applicationmust do to usea physicalfile.
1. Obtain a deviceconnection.
This ìs necessaryfor two reasons.When your task createsthe physicalfile,the device
connectionteÌls the ExtendedI/O Systemwhich deviceis to containthe file and that
the tile must be a physical fiìe.
You mustcreatea program-here it is caÌleda "systemproEam'!-that usesthe
LOGICAL$ATTACH$DEMCE systemcall to obrainrhe deviceconnecrion.When
issuingthis caìI,the systemprogrammust usethe devicenamethat wasassignedto
the deviceduring s)'stemconfiguration.For instructionsas to how to assignnamesto
devices,refer to the -Ettendedikùlx II Intemctive Conliguration Utitit Refercnce
Manua[.
Becausedevicescannotbe multiply-attached,
you mustwrite your systemprogramso
as to call LOGICAL$ATTACH$DEVICE only once. The
LOGICAI$ATIACH$DEVICE systemcall obtainsa deviceconnectionand catalogs
the connectionunder the logicalnameprovidedby the systemprogram. Other tasks
wishingto usethe deviceconnectìoncan then look up the connectionby usi_ng
the
device'slosicalname.

Extended
I/O Use/s Cuide

PHYSICALFTLES

The LOGICALITATTACII$DEVICtr systemcall is describedin -eÍerúecl |RMX II
ExtendedI/O SystemCalls ReferenceManual.
2. Obtain a lile connection.
To obtain a file connection,your applicationtask shoulduseone of the followingtwo
systemcallsr S$CREATE$FILEor S$ATTACH$FILE. The decisionas to which
systemcall to usedependsupon your task'sawareness
of the existerceof the file.
There are two circumstances
underwhichyour task shoulduseS$CREATE$FILE to
obtain a connection.The fi-rstcircumstanceis whenyour task doesnot know whether
the file aheadyexists,and the secondis whenyour task knowsthat the file doesnot
yef exrsa.
When invokingthe S$CREATE$FILEsystemcall,set the path$ptrparameterto
point to a STzuNG containingthe logicalnameofthe device(enclosedin colons,as in
:F0:). This tells the ExtendedI/O Systemwhich deviceyou want as your physicalfile.
If, on the other hand,your task is certaintha! the file alreadyexists,usethe
S$AfiACH$ FILE systemcall to obtair the file connection.Yoùr task can do this in
either of two v/aysl
.

Iî can set the path$ptrparameterof the call to point to a STRING containingthe
device'slogicalnamesurroundedby colons(asin tF0:).

If the task knowsa logicalnamefor a connectionto the file, it can set the path$lrlr
parameterof the call to point !o a STRING containingthe connection'slogical
namesurroundedby colons(as ìn :DATABASE:).

Either way,the ExtendedI/O Systemreturnsa connectionto the physicalfilr
TLis carelul Llislirctionbetweenthe S$CREATE$FILE and lh€ S$ATTACH$FILE
systemcallsis necessaryto be consistentwith namedfiles. If you want your
applicationto work with namedfiles as well as physicalfiles,you must maintainthis
consistenry.
3. Open rhe file connection.
Use the S$OPENsystemcall to open the connection.When openingthe connection,
your task must specil] whetherthe taskplansto read,write, or do both usingthe
connection.The task must aisospeciryhow manybuffersthe ExtendedI/O Systemis
to use when reading liom o. writing to the file. The Ertended |RMX II Ertended I/O
SlstemCallsRekrenceMazaal explainshow to do this.
4. Manipulatethe file.
There are four systemcallsthat can be usedto read,wrìte, or otherwisemanipuiate
your physicalfile:
.

The S$READ$MOVE and S$WRITE$MO\aEsystemcallsare usedfo read and
write informationfrom (to) the physicalfile.

Extended
I/O Use/s Cùide

5-3

PIrySICAI,FII,ES

TheS$SEEKsystemcallcanbe usedto manipulate
thefile connection's
file
pointerif the deviceis :ì randomdevicesuchasdisk,diskette,or bubble.(If you
arewritìnga devicedriverfor a magnetic
tapeunit,youcandesignit to support
S$SEEK. Refer to the ExendedLRMXII DeticeDivefi Uset\ Guidz.)

The S$SPECIAL
systemcallcanbe usedto requestdevicedependent
functions
yoùrtaskscanusetheS$SPECIAL
from the devicedriver.For example,
system
callto havetheExtended
I/O Systemformata diskfor usewith the iRMX II
preventa task
OperatingSystem.Be awarethatuseof specialfunctionsgenerally
from beingdeviceindependent.

All four of thesesystemcallsare describedinthe ExtendediRtulX btended I/O
SystetuCalLsRelercnce
Manual.
5 . Closethe file connection.
Use the S$CLOSE systetÌìcall to close the colloe€tioll. Nolc lhàt ]our applicatio0 calÌ

repeatsteps2, 3, and4 anynumberoi times.TheS$CLOSEsystemcallis described
in the ExtendcdiRMX

&tcndÌd I/O Slstcm Calb RclerenceManual.

6. Delete the connection.
Use the S$DELETE$CONNECTIONsystemcall to deletethe connection.This is
only necessaryifthe tasksofyour applicationare completelyfinishedusingthe file.
This systemcall is descîibed in the ExtekàedíRMX II ExtendedI/O SystemCalk
ReferenceManual.

7. Requestthat the devicebe detached.
Lct the systemprogramknow whenyour task no longerneedsthe device. The system
programcan caìl LOGICAI-$DETACH$DE\"'ICE to derachthe device. The
OperatingSystemkeepstrack of the nÌrmberoftasks usingthe deviceand avoids
detachingthe deviceuntil it is no longerbeingusedby any task. Only then doesthe
OperatingSystemactuallydelachthe device.

5-1

Extended
l/O Usefs Guide

6.1 oVERV|EW
Sfeam files provide a meansfor one task to sendlargeamoùntsof informationto a
secondtask,evenwhen lhe two tasksare in differentjobs. Be awarethat streamfiles are
only one of severaltechniquesfor job-to-jobcommunication.lf you are not familiar wirh
othcr techniques, refer to the Extend,ed|RMX II Programníng Techtiques Refercnce
Mantnl.
The aspectof streamfiles that makesthem very usefulis that they allow a task to
communicatewith a secondtask as thoughthe secondtaskwere a device.This extends
the notion of deviceìndependence
to includetasks.
Srncetrvo tasks(calledthe readingtask and the writing task) are involvedin usingeach
streamfile, the tasksmustcooperate.There are a largenumberofprotocols that work,
but.lhe onesprovidedlater in this chapterserveas good ifustrations.

6.2 SUGGESTION
FORMAINTAINING
FILEINDEPENDENCE
Ifyou would like your readingand writing tasksto be able to usenamedfiles or physical
files rather than only streamfiles,you shouldjncorporatea third task into the protocol.
The purposeof this third task is to perform the one part of the protocolthat dependson
the kind of file beingused-the creationof the file.

6.3 STREAMFILE PROTOCOLS
The interactionbetweenthe tasksis dividedinto three protocols--oneeachfor the
creating,w.iting, and readingtasks. Ifyou chooseto avoid usinga separatetask to create
the file, you can havethe writing taskperform the creatingprotocolbeforeit performsthe
writing protocol. However,by eliminatingthe creatingtask,you iorce the writing task to
requirethat only streamfiles be used. To allowboth the readingand writing tasksto be
independentof the kind of file beingused,you shouldusea separatecreatingtask.
The followilg protocolswork cvcn if thc thrcc tasksare in differentjobs. They alsowork
resardlessoithe order in which thev are executed.

ExtendedI/O Usefs Guide

ó-t

STREAM FILES

Task
5.3.1Protocol
for theCreating
The creatingtask is responsibÌefor obtaininga deviceconnectionto the streamfile
pseudodevice,and for cr€atingthe str€amfile. It alsomust catalogthe file coînection
under a logicalnameso the readingand writing taskscan attachthe file. Rememberthat
this task is not deviceindependent-itworks only for streamfiles. This protocol involves
rwo sreps:
1.

Creatinga streamfile.
While configuringthe Extendedf/O Syst€m,the personthat configuresyour system
must enter a configurationparameterthat representsa logicalnamefor the stream
file device. During systeminitialìzation,the ExtendedI/O Systemattachesthe
streamfile pseudodeviceand catalogsthe deviceconnectionunder that logical
name. Your taskscan then usethe logicalnameto obtain the deviceconnection.
To understandthis protocol,assumethat the logicalnameis STREAM. (Your
systemmight use a different logicalname. To be sure,consultthe person(s)
responsiblefor conîiguringyour system.)
To createa streamfile, the creatingtask needonly invoke the S$CREATE$FILE
systemcall usinga path$ptrparameterpoiÌtting to a STRING of the followinglorm:
:STREAM:
whereSTREAM is the logicalnamefor the streamfile deviceconnection.The
S$CREATE$FILE systemcall, which is descîibed ìn the Extended|RMX II Ertended
I/O SystemCa s RefercnceManual rctrrns ^ connection to the newly created
streamfile.

Catalogthe file connectionundera logicalname.
The creatingtask shouldinvokethe S$CATAIOG$CONNECTION systemcall to
establisha uniquelogicalname(for example,SF23)for eachspecificstreamflle.
The readingand writing taskscan then usethe logjcalnameto attachthe fiìe. The
S$CATAIOG$CONNECTION systemcall is describedin the tirended íRMX II
ExtendedI/O SJsten Calh ReferenceManual.

6.3.2Protocolfor theWritingTask
Thewritingtaskmustperformfivestepsin orderto ensùrethat it establishes
communicatìon
with thereadingtask.Thestepsare
1.

Obtaina connection
to thestreamfile.
The writing task shouldusethc logicalnamc oî the file connection(for example
SF23)and invokethe S$ATTACH$FILE systemcall to obtainthe file connection
To do this, the task shouldset the path$ptrparameterofthe systemcall to point to
a STRING containingthe file connection'slogicalnameenclosedin colons(as in
rSF23
r).

6-2

Extend€d
I/O User'scuide

STRIAM FILES

Open the file connectioofor writing.
Use the S$OPENsystemcall to openthe file connectionfor writing. Set the
connectionparameterto the token for the lile connection,and set the mode
parametefto write.

Write informationto the streamfile.
Use the S$WzuTE$MOVB systemcall as often as desired!o write informationro
the staeamlile. Use th€ token for the file connectionas the connectionparameter-

Closethe connection.
When finishedwriting to the streamfile, use the S$CLOSEsystemcall to c.Iosethe
connection.Note that after this step,the writing task can repeatsteps2, 3, and 4
any numberof times.

Delete the connection.
Use the S$DELETE$CONNECTTONsystemcall to deletethe connectionto the
streamfile.

6.3.3 Protocolfor the ReadingTask
The readjngtask must perform the followingsevenstepsto successfully
read the
inlormationwrilten by lhe wriring lask:
l.

Obtain the file connectionfor the streamfile.
The readinglask shouldusethe file's logicalname(for example,SF23)and invoke
the S$ATTACH$FTLEsystemcall to obtain the file connection.To do this, the task
shouldset the path$ptrparameterof the systemcall to point to a STRING
containingthe lile connection'slogicalnameenclosedin colons(as in :SF23:).

Open the fiìe connectionfor reading.
The task shouldusethe S$OP!,Nsystemcall to open the file connectionfor
reading. Sei the connectionparameterto the token for the file connection,and set
the mod€parameterto read,

Read informationfrom the sireamfiìe.
The task shouldusethe S$READ$MOVE systemcalì as often as neededto read
informationfrom the streamfile. Use the token for the file connectionas the
connecllonparameter,

Closethe connection.
When finishedreadingfrom the streamfile, the task shouldusethe S$CLOSE
systemcall to closethe connection.Note that after this step,the readingtask can
repeatsteps2, 3, and 4 any numberof times.

ExtendedI/O flsefs Gùide

STR,EAM
FILES

Delete the connection.
The task shouÌdusethe S$DELETE$CONNECTIONsystemcall to deleterne
connectionto the streamfile.

DeÌetethe file's logicalnamecreatedby the creatingtask.
The task shouldusethe S$UNCATALOG$CONNECTIONsystemcall to delere
the logicalnamefor the flle. In our example,this logicalnameis SF23. Do not
deletc thc logicalnamefor the streamfile device.

Delete the file connectioncreatedby the creathg task.
The readingtask shouldusethe S$DELETE$CONNECTIONsystemcall to delere
the file connectionthat the creatiogtask obtained. Oncethis connectionis deleted,
the ExtendedI/O Systemautomaticallydeletesthe streamfile.

6-4

Extended
I/O Usefs Guide

7,1 OVERVIEW
The ExtendedI/O Systemis a configurabìelayer of the OperatingSystem.It contains
severaloptionsthat you can adjustto meetyour specificneeds.To help you make
configurationcboices,Intel providesthree kindsol intbrmation:
.

A list of configurableoptions

Detailed informationaboutthe options

Proceduresto allow you to speciryyour choices

The followingscctionsdcscribethe configurableoptions. To obtainthe secondand third
categoriesof information,refer to the Àrtended|RMX II húeructî\,eConfgumtionUtiliE
ReferenceManual-

7.2 t/O JOBOBJECTS
When you conligurethe ExtendedI/O System,you can specirythe following
characteristics
that dealwith iRMX lI objects:
.

Default sizeof objectdirectoriesfor I/O jobs and for the ExtendedI/O System.

User objectsto be creried at initialization;eachconsistsof e nsme for the userobject
and one or more userlDs. Seethe sectionUser Objectsin Chapter4 for more
information.

Logicalnamesfor devices;theseare catalogedin the rootjob's objectdhectory.

7.3 INTERNAL
BUFFER
SIZE
You can specif] the sizeol the internalbuffersthat the ExtendedI/O Systemusesto
transferdata from files.

ExtcndedI/O User'sCuide

7-1

CONFIGURATION
OF THE EXTENDEDI/O SYSTEM

7.4 tlo JoB GHARACTERTSTTCS
WhenyouconliguretheExtendedI/O System,
youcancreateI/O jobs. Whenthe
Operating System is initialized, thesejobs are also created. (See the E\tended íRMX

ExtendedI/O SystemCalk Reference
Manual for a descriptionofI/Ojobs.) You can
speciryasmanyjobsasyouneed:thecharacteristics
thatyouspeci$for eachjob
coÍespondto theparameters
of the RQE$CREATE$IO$JOB
systemcall. For eachjob,
youspeci$
r

Nameof defaultprefixfor thisjob

Nameof defaultuserobjectfor thisjob

Minimumandmaximumsizeof theI/O job'smemorypool

Addressof, andmodeof, thejob'sexception
handler

whetherto includeparameter
validationfor ùe I/O job

Priorityof inìtialtaskin job

Task,datasegment,
andstackaddresses

Stacksizefor initialaask

Whetherfloating-point
instructions
areusedin thejob'sinitialtask

7.5 AUTOMATIC
BOOTDEVICERECOGNITION
Yoù can configurethe ExtendedI/O Systemso that it automaticallyattachesthe device
from which the OperatingSystemis bootstraploaded. This deviceis then catalogedand
know as the systemdevice.Automatic Boot DeviceRecognitionallowsyouto refer to
files on the volumeftom which the deviceis bootstraploadedwithout knowingthe exact
physicaldeviceon which the files reside. Ifyou want to hclude this feature,you can
specifuthe characteristics
of the SystemDevice.

Extended
I/O Useis cuide

CONFIGURA.TION
OF THE EXTENDEDI/O SYSTEI,I

7.6 INITIALIZATION
ERRORREPORTING
Duringlhe configuration
process,
youcanelectto havethe systemreportEIOS
initializationerrors.Ifyou respond"Yes"to the ReportInitializationErrors(RIE)
parametelon tlìe"Nucleus"
screen,thc ol)srdlingsyslemrcportsinitializalioncrrorsfrom
all subsystems.
On encountering
a EIOSinitializationerror,theoperatingsystemreturns
controlto the monitorafterwritìngthefollowingmessage
to theconsole:

If Report InitializationErrors is not configuredìnto your systemor the iSDM monitor is
not present,the initial EIOS taskplacesthe EIOS lD code (3) and the correspondiJìg
error code into the fi-rsttwo wordsofthe Nucleusdata segment(lE0:0000H). It then
gocsinto an infinile error loop.

Ertended I/O Use'js Guid€

4.1 DATAWPES
The followingdata R?esare reaognizedby the iRMX II OperatingSystem:
BOOLEAN

A byte that is consideredto havea value of TRUE if ir is 0FFH,
and FAISE if it is 00H. InPL/M286,
DECLARE BOOLEAN LITERAILY 'BYTE';

BYTE

An unsignedeight-bitbinarynumber.

DWORT)

A Lìnsigned
four-bytebinarynumber.

INTEGER

A signedtwo-bytebinarynumber. Negativenumbersare storedin
two's'complementform,

OFFSET

A word whosevaluerepresentsthe distancefrom the baseof an
80286segment.

POINTER

Two consecutive
wordscontainingthe selectorof a segmentand an
offset into the segment.The offsetmust be in the word havingthe
lower address.

SELECTOR

An index into a descriptortable that ide[tifies a particularmemory
segment The descriptortable entry lists the segment'sbase,ljmit,
qTe, and privilegelevel.

STRTNG

A scquenceof consecutive
b)'tes. îre valuecunraincrlil the lirst
byteis the numberofbytes that follow it in the string.

TOKEN

A selectorthat containsthe logicaladdressof an obje,ct.The
selectorrefèrsto an entry in the descriptortablethat lists the
physicaladdressof the objecr.A rokenmusrbe declaredliteralÌya
SELECTOR,

WORD

An unsignedtwo-bytebinary number.

E\rendedI/O UsedsCuide

OBJECT

B.1 OVERVIEW
Thisappendix
liststhe typecodesfor all iRMX II objects.In addirion,it documenrs
rhe
resourcerequirements
of theExtended
I/O System.

8,2 OBJECTTYPES
Each iRMX II obj€cttype ìs kruwn wiLhiniRMX II syslemsby meansof a numericcode.
TableB-1 lìststhe typeswith their codes.

TableB-1. TlTe Codes
Objecllype

Task
Semaphore
R6gon
Extension

NumericCode
1
2
3
5
6
7
8

Connectìon
l/O Job
LogicalD€vce
UseÉCreated

101
300
301
vafiesfiom 8cìcrcH
to
oFFFFHdépending
on the
CREATE$EXTENSION

The firsterghlobj€c1s,p us usef.createdcomposites,aredescribedî lheExtende.díRMX II
Nucleus User's Guitle. l/O tobs and loqicald(ryices
aredescbedinChaptef
3 oflhismanual.
Usels and connectionsare d€scrib€clin the LÌte ,tdediRlrlx II Bdsic I/O SystentUser's

Guíde.

ExtendedI/O User'sGuide

B I

OBJECT TYPF]S AND RESOI]RCE REQI]IREMENTS

8.3 RAMREQUIREMENTS
The followinginformationhelpsestimatethe amountof RAM neededto use the
Exterded I/O SysteÍr. The descriptioùsthal follow stdte€rplicilly from whichpool the
RAM is taken. You shouldusethis informationwhen decidinghow largeto make the
memorypoolsof the jobs ìn your application.Be awarethat this informationappliesonly
to the current releaseof the iRMX II OperatingSystemand may shrink or grow in iuture

8.3.1 Attaching a Logical Device
Eachtime oneofyoùr tasksusestheLOGICA$ATTACH$DE\4CE systemcall,the
Extendedl/O Systemuses98 (decimal)bytesol RAM fromyourjob'spooland64
job createddurin-q
(decimal)bytesof RAM from thepoolof theExtended
I/O System
the
process.This RAM is in additionto the RAM requiredby the BasicI/O
configuration
Systemfor a deviceconnection.
Bothquantitiesof RAM areeventually
returnedto the memorypoolsfromwhìchthey
originated,
but theyarereaurned
at differenttimes.The memorytakenfrom the
ExtendedI/O Systempool is returnedonlywhenthe deviceis detached.In contrast,the
memorytakenfrom yourjob'spool is returnedassoonthc
LOGICAI$ATTACH$DEMCEsystemcallfinishesrunning.

8.3.2 Creatingan l/O Job
Wheneverone olyour taskscreatesan I/O job, the Ertended I/O Systemuses176
(decimal)b)'tesof RA.M from the pool of the t/O job beingcreated. This RAM is in
addition to the RAM usedby the Nucleusto createthe job. All of this memoryreturnsto
the pool of the parentjob after the I/Ojob hasbeendeleted.
ln addition to the memoryrequirement,CREATE$IO$JOBand
RQE$CREATE$IO$JOBalsorequirefjve entriesin the objectdirectoryof rhe l/O job
beingcreated. Refer to Appendi\ D to seehow theseentriesare used.

B-2

ExtendedI/O User's Guide

RTQUIRE\ÍI\TS
OBJECTTYPESAND RESOURCE

8.3.3 Openinga Connection
Wheneveroneofyour rasksusestheS$OPENsystemcallro opena file connection,
the
Eferded I/O SystemusessomeRAM from thepoolof the callingjobto createobjects.
Thepreciseamountof RAM rcquireddepends
onwhethertheconnection
is openedfor
bufferedI/O or nonbuffered
ì/O. lfthe connection
is not buffered,the Efended l/O
Systemuses64 (decimal)bytesof RAM. On the otherhand,if theconne-ction
is buffered,
youmustusethefollowingexpression
to computethe amountof RAM usedasa function
ofthe buffersizein b)'tes(S)andthe numberofbuffers(N):
numberof bytes= 80 + 5N +N(S+64)
Regardless
cfwhethertheconnection
is buffered,all RAM returnsto the memorypool
whentheconnecionis closedor deleted.

8.3.4 OtherRAMRequirements
For systemcallsother than thosediscussed
above,the ExtendedI/O Systemhasvarying
memoryrequirements.However,you can safelyassumethat when you make an Extended
I/O Systemcail,thc call requiresno more than
.

300 (decimal)bytesof your job's memorypool.

400 (decimal)bytesof the callingtask'sstack.

This RAM returnsto yourjob's pool as soonas eachsystemcall finishesrunning.

8.4 OBJECTCOUNTS
Becauseeachjob has a m:r:ximum
numberof objectsthat it can own,you shouldknow how
many objectsthe Extendedl/O Systemcreateswhile executingsystemcalls. You can
assumethat the ExtendedI/O Systemcreatesno more than 10(decimal)objectsdùring
the executionof any systemcall.
Furthermore,exceptin a lèw cases,all of theseobjectsare deletedbefore the systemcall
hasfinishedrunning. The few exceptionsare the systemcallsthat explicitlycreateobjects
at the requestofyour applicationtasks. Two exaúplesof systemcallsthat explicitly
and
createobjectsare the S$ATIACH$FILE systemcall (whichcreatesa file conne,ction)
the LoGICAL$ATTACH$DE!'ICE systemcall (whichcreatesa deviceconnection).

Extended I/O Uscr's Cùidc

c.1 oVERVTEW
The iRMX ll Extended
I/O Systemusesconditioncodesto informyourtasksof any
problemsthat occurduringlhe execution
of a systemcall. If no problemsoccurandthe
systemcallrunsto completion,
the Extended
I/O Systemreturnsan E$OKcondition
code. Otherwisc,thc Extcndcd I/O Systemreturnsan exceptionalconditioncodc.
The meaningof a specifìcexceptionalconditioncodedependsupon the systemcalì thrt
returnsthe code. For this reason,this appendixdoesnot list any interpretations.
This appendixprovidesyou with the numericvalueassociated
with eachconditioncode
that the ExtendedI/O Systemcan return. To usethe exceptioncodevaluesin a symbolic
manner,you can assign(usingthe PL/M-286 "LITERALLY" statement)a meaningful
nameto eachof the codes,or you can usethe ERROR.LIT file containedin the
:SD:/RMX286/INC direc!ory.
The followinglist correiatesthe nameof the conditioncodeto the valuerhat rhe
ExtendedI/O Systemactùallyreturns. The list is dividedinto three parts;one for the
normal conditioncode,one for exceptioncodesthat indicatea programúing error, and
one lbr exceptioncodesthaî indicatean envfuonmental
condition.A programmererror ls
a conditionthat is preventableby the callingîask. An environmentalconditionis rn
exceptionconditioncausedby circumstances
beyondthe control ofthe callingtask.
Condition codes are describedin the tÌrended |RMX II ExtendedI/O fistem Calh
Reference
Manual.

C.2 NORMALCONDITION
CODE
NAME OF CONDITIOTE$OK

Extendedl/O Usefs Guide

DECIMAL

HEXADECIMAL

c-1

CONDITIONCODES

C.3 PROGRAMMING
ERRORS
NAME OF COND]TION
E$ZERO$DIVIDE
E$OVERFLOW
E$TYPE
E$PARAM
E$BAD$CALL
E$NOUSER
E$NOPREFIX
E$BAD$BUFF
E$NOT$LOG$NAME
E$NOT$DEVICE
D$NOT$CONNLCTION

DECIMAL
32168
32'769
32770
327',l2
32801
32802
32803
32432
32833
32831

HEXADECIMAL
8000H
8001H
8002H
8004H
8005H
8021H
8022H
8023H
EO4OH
8041H
8042H

C.4 ENVIRONMENTAL
CONDITIONS
NAME OF CONDITION

E$TIME
E$MEM
E$LIMIT
E$CONTEXT
E$EXIST
E$NOT$CONFICURED
E$FEXIST
E$FNEXIST
E$DEVFD
E$SUPPORT
E$EMPTY$ENTRY
E$DIR$END
E$FACCESS
E$FTY?E
E$SHARE
E$SPACE
E$IDDR
E$ro
E$FLUSHING
E$ILLVOL
E$DEV$OFFLINE

DECIMAL

HEXADECIMAL

1
2
4
5
6
8
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46

IH
2H
4H
5H
6H
8H
20H
21H
22H
23H
24H
25H
26H
27H
28H
29H

2AH
28H
2CH
2DH
2EH

ExtendedI/O uset's Guide

CONDITIONCODES

C.4 ENVIRONMENTAL
(continued)
CONDITIONS
NAMF OF CO\DIT]ON

DECIMAL

E$IFDR
E$FRAGMENTAT]ON
48
E$DIR$NOT$EMPTY
49
E$NOT$FILE$CONN
50
E$NOT$DEVICE
:)l
E$CONN$NOT$OPEN
52
E$CONN$OPEN
),
E$BUFFERED$CONN
54
E$OUTSTAN'DINO$CONNS)J
E$AIREADY$1\TTACHED
E$DEV$DETACHING
5'7
E$NOT$SAME$DEV
Jò
E$ILLOGICAT-$RENAME 59
E$STREAM$SPECIAL
60
E$INVALID$FNODE
61
E$PATI]NAME$SYNTAX
62
E$FNODE$LIMIT
63
E$LOG$NAME$SYNTAX
64
E$CANNOT$CLOSE
65
E$IOMEM
66
E$MEDIA
68
E$LOG$NAME$NEXIST
69
E$NOT$OWNER
10
E$IO$JOB
7l
E$UDF$FORMAT
72
E$NAME$NEXIST
73
E$UID$NEXIST
E$PASSWORD$MISMATCH75
E$IO$UNCLASS
80
E$ro$soFr
81
E$IO$I]ARD
82
E$IO$OPRINT
83
E$IO$WRPROT
84
E$IO$NO$DATA
85
E$IO$MODE
86
E$IO$NO$SPARLS
87
E$IO$ALT$ASSIGNED
88

Extended
I/O User'scuide

I{E)'ADECI À,LA.L
2FH
30H
3lH
32H
33H
34H
35H
3óH
37H
38H
39H
3,AH
3BH
3CH
3DH
3EH
3FH
40H
41H
42H
44H
45H
46H
47H
48H

49H
4AH
4BH
50H
51H
52H
53H
54H
55H
56H
5',l]J
58H

APPENDIX
D
USEOFOBJECT
DIRECTORIES
BY
THEEXTENDED
UOSYSTEM

D.1 OBJECT
DIRECTORIES
TheExtendedI/O Systemcatalogs
entriesin the objectdirectoryof eachI/O job andin
theobjectdirectoryof thesystem's
providesa list of the names
rootjob. Thisappendix
that theExtendedl/O Systemuses.Do not redefineanyofthe nameslistedin this
aDDendix.
RQGLOBAL

The ExtendedI/O Systemusesthis nameto identifi the globaljob
for eachI/O job. Wlenever you createan I/O job, the Extended
I/O Systemautomaticallycatalogsthe token for the globaljob in
the objectdirectoryof the I/O job, If you wish to redelìnethis
nametyou may. But doing so might alter the interpretationof any
logicalnamesthat are catalogedin the objectdirectoryofyour
job'sglobaljob.

R?IOJOB

Wheneveryou createan I/O job, the Extendedl/O System
catalogsan objectunder this namein the objectdirectoryof the
t/Ojob. Do not redefinethis name!

R?MESSAGE

Wheneveryou createan I/O job, the Exîendedl/O System
cataìogsan objectunder this namein the objectdirectoryof the
I/O job. Do not redefinethis namel

R?IOUSER

Wheneveryou createan I/O job, tlÌe ExtenderJI/O System
catalogsan objectunder this namein the objectdirectoryoî the
l/O job. Do not redefinethis name!
The ExtendedI/O Systemusesthis nameto catalogthe default
prefi\ for eachI/O job. If you modiry lhe definirionassociared
with this nameby invokingthe CATALOG$OBJECT systemcall,
you changethejob's defaultprefix. Furthermore,ifyou catalogan
objectother than a deviceconnectionor a fìle connectionunder
this name,the ExtendedI/O Systemgeneratesan exceptional
conditioncodewheneveryou attemptto use the defaultprefix.

With the exceptionof RQGLOBAL and $, you shouldnot usethe CATALOG$OBJECT
systemcall to modify any of the definitjonsdescribedhere. If you do changeany of them,
you might causethe Extendedl/O Systemto behavein an unexpected,unpredictable,and
undeslable manner.

Extended I/O User's Cuide

D-l

TISEOF OBJECTDIRECTORIESBY THE EXTENDED I/O SYSTEM

The Extended
I/O Systemusesobjectdirectories
for two otherpurposes:

n_t

Wheneveryou usethe CATAIOG$CONNECTION systemcall to definea logical
namefor a connection.
theExtended
I/O Systemcatalogs
theconnection
in the object
dfuectory
of thejob thatyouspeciry.

Whenever
yolrusethe LOGICAUATTACH$DEVICEsystcmcall,thc ExtcndcdI/O
Systemcatalogs
the deviceconnection
in theobjectdi.ectoryof the system's
rootjob.

Extended
I/O Use/s cuide

E.1 COMPAT|BtLtW
BETWEEN
THETWOt/O SYSTEMS
Many of the systemcallsin the BasicI/O Systemhavecounterpartsin the ExtendedI/O
System.For example,the A$CREATE$FILE systemcall of the Basicl/O System
pedorms a function analogousto the S$CREATE$FILEsystemcall of the ExtendedI/O
System.So it is reasonableto askif connectionscreatedby one systemcan be usedby the
otneI.
The answeris yes,unlessthe connectionis open. For example,your applicationsysîetn
can usethe S$CREATE$FILE ExtendedI/O Sysremcall ro crearea file and obtain a
connectionto the filc. Bccausethe connectionis not open,your applicationsysterncan
usethe connectionwìth any BasicI/O Systemcall that doesnot require an open
connection-For instance,the coonectioncan be usedwith A$RENAME$FILE or lvith
A$GET$FILE$STATUSbecauseneither of thesesvstemcallsrequire that the connecúon
be open. However.the connectioncannotbe use.lwith a$ngaOor A$WRITE. hecause
bothofthesesystemcallsrequirethat lhe connertionhe nfen.
The samerestrictionappliesif the connectionis c.eatedusingthe BasicI/O System.The
connectioncan be usedwith any ExtendedI/O Systemcall as long as the systemcall does
nol requfe an open connectlon,
In general,you can creatc,dclete,checkstatus,or attachusingeither kind ofsystenrcall_
But onceyou haveopenedthe connection,you must ùsea read,write, truncate,or special,
function systemcall provìdedby the I/O Systemthat you usedto open rhe connection.
Then, onceyou haveclosedthe connection,you can againusesystemcallsfrom either
I/O System.

Extended I/O User's Guide

E I

F.I INTRODUCTION
The iRMX ll OperatingSystemis basedon the iRMX I OperatingSystem.Therefore,
the iRMX Il versionof the ErtendedI/O Systemoperatesalnost exacdylike its iRMX I
counterpart. However,there are a few differencesbetweenthe two.
Thc followingappendi! ourlinesthe differencesbetweenlhe two ExtendedI/O Systems.
Thesesectionsare intendedfor readerswho are a]readyfamiliar with iRMX I and who
would like a quick overvicwof the differences.Thosewho a.en't familiar wirh eirher
ExtendedI/O Systemshouldskip this appendir.

F.2 EXTENDED
MEMORYPOOLSIZES
One of the major featuresof the iRMX II Operathg Systemis its supportof the 16Mbyte memory-addressing
capabilityof the 80286processor.The ExtendedI/O System
takesadvantageof this featureby allowingthe I/O jobs you createto havememorypools
as large as 1óM bytes. A new systemcall, RQE$CREATE$IO$JOB,providesthis ability.
RQE$CREATE$IO$JOBworks exactlylike the CREATE$IO$JOBsysremcaII available
with iRMX I systems.However,two of its parameters(pool$minand pool$max)have
beenexpandedfrom r&ORDs to DWORDs. This allowsyour memorypoolsto be as
large as 16M bytes.
RQE$CREATE$IO$JOBis not a replacementfor CREATE$IO$JOB,but an additional
systemcall that hasbeen addedto the iRMX II ExtendedI/O System.
CREATE$IO$JOBis still availablefor compatibilitywith iRMX I systems.However,if
you use CREATE$IO$JOB,your memorypoolswitl be limited to 1M byte.

F.3 PROTECTION
FEATURES
The iRMX II Extended
I/O System,
like the iRMX II BasicI/O System,
givesyou
increased
protection.If youtry to readfrom or writeinto memorysegm€nts
thatdo not
havetheproperaccess
tlpe, or ifyou attemptto reador writepastthe endof the
segment,
youwill receivea newexception
codecalledE$BAD$BUFF.The systemcalls
S$READ$MO\€ andS$WRITE$MOVE
caneenerate
thisexceotion
code.

ExtendedI/O Usefs Guide

F-l

iR}fX@I AND iRMX@II EXTENDEDI/O SYSTEMDIFFERXNCES

when youuseS$READ$MOVE,
thebufferof memoryusedto storethedatareadin
(youarewritilg informationto thìs
from the peripheraldevicemusthavewriteaccess
whenyouuseS$WRITE$MOVE,
thebufferof m€mory
memorysegment).Likewise,
containingthe data to be v.ritten musthave.ead access(you are readinginformation
from the memorysegment).
other ExtendedI/o Systemcallsmake additionalprotectioncheckson the parameters
you enter. Supplyìngincorrectparameterscan causeE$PARAM exceptioncodes.

F.4 NEWSYSTEMCALLS
Th€ iRMX II Extend€d I/O Systen has two systEnìcalls that are not pr€sent in th€ iRMX

I Extended
l/O System:S$GET$DIRECTORY$ENTRY
and
SSGET$PATH$COMPONENT.
S$GET$DIRECTORY$ENTRY
letsyouretrievethe
nameof anyfile in a directory.S$GET$PATH$COMPONENT
looksup thenameof a
file asit is knownin its parentdirectory.Bothof thesesystemc.lllsprovidesynchronous
versionsof services
that arealsoavailable
with theBasicI/O Svstem.

F-2

Extended
I/O User'scuide

A
Accessmask 4-11
bit mealings4-11
example 4-12
Advantagesof buffers 2-5
Applicationsusingonly sequentialI/O l-5
Asynchronoussystemcalls 1-2
Attachinga logicaldevice B-2
Automatic boot devicerecognition 7-2
Automatic bufferingof I/O requests 1 3

B
Bullèrsizeconsiderations
2-6

c
Characte.istics
of l/o jobs 7-2
Choosing
anI/O system1-1ro l-6
Compatibility
betweentheBIOSandEIOSsystemsE-l
Computingaccess
ior file connections
4-12
Conditioncodes(seeAppendix
C) C-1
envúonmentalu-2, J
normal c-1
programmingcodes C-2
Configuringthe ExtendedI/O system,seechapter71
Connectionsand physisalfiles 5-2
Connectionsbetweeniasksand deviceunìts 3-2
ControÌlingaccessto files 4-8

D
Dàla t)?es A-1
Default prefix 3 9, 4,19
Default user 4-19
Delault user objectfor a job ,{-9
Deviceconnections3-5
Devicecontrollersand deviceunits 3-1
Dynamiclogon ficilities 4-10

ExtendedI/O l]sefs Guide

Ind€x-1

INI)EX

E
EIOS algorithmfor S$ATTACIJ$FILE systemcall 4-13
FTOSsystemcallsfor nimed files 4-15
changingaccess4-17
creatingand deletingI/Ojobs 4-18
cleleting
and renamingliles 4-17
deletingconnections
4-17
manjpulatjng
drta 4-16
miscellaneous
functions4-18
obtainingand deletingconnections
4-15
obtainingstatus4-17
usinglogicalnames4-17
ERROR.LITfile C-1
Frlended I/O Systemfeatures
16M-Bytememoryaddressability2-1
accesscontrol 2-5
automalicreattàchment
of devices2-7
bufferingwith overlappedI / O 2-5
deviceindependence2-2
file independence2-4
Iile sharing 2-5
four file types 2-3
namedfiles 2-3
physicalfiles2-3
remole fìles 2-3
streamfiles 2-3
logìcalnamesfor files and devices2-7
protectionfealures 2-2
separationof file lookup and file open operations2-4
supportof many kinds of devices2-2

F
lìile access
list 4-11
Iìile connections3-5
Filepointers3-6
Files 3-2
Formula for RAM usedby bufferedconnectionB-3
Four string forms permittedfor the path$ptrparameter 4-6
Fundamentalconceptsof the EIOS, seechapter31

G
Generalrequirements
for theEIOS B-3
Globaljob3-8,9

Index-2

Extended
I/O Uset'sGuide

INDEX

H
Hiererclical namingof file 4-2
High performanceapplicationsusingRandomI/O l-5

I
l/o jobs 3-B
exitingfrom 3-8
Internalbuffersize 7-1
IRMX.N'ET 4.IO

L
Logical names 3-7

andobjectdirectories3-7
noncasesensitive3-7
slartaxfor 3-7
Logicaldeviceobject3-5

M
Maintainingfile independence5-2,6-1
Memory requirementsof the EIOS system 1"4
Multiple files on a singlevolume 4-1

o
Objectdirectories 3-7,D-1
$ D"1
R?IOJOB D-1
R?IOUSER D.1
R?MESSAGED-l
RQGLOBAI, D.I
Object t)?es,numericcodes B-1
Openinga connection B-3
Overviewof namedfiles 4-19

P
Path syntar 4-6
Path$ptrparameter 3-9,4-6
Prefi\es
definition 4-5
Protocolsfor streamfiles 6-1
the creatingtask 6-2
the readingtask 6-3
the writirg task ó-2

Extended
I/O User'sGuide

Index-3

INDEX

R
R?IOUSER4.9
RAM needed for the EIOS B-2

Reasonfor havingtwoI/O systems1-1
Rootjob3-8

s
S$CIIANGE$ACCESSsystemcall 4-12
SpecialuserIDs 4-14
systemmanager 4-14

woRLD 4-14

Stcps for obtaioing a ncw IiI€ conn€clion

Stepsin usingphysicalfiles 5-2
Streamfiles,seechapter61
Subpaths4-6
Synchronous
systemcalls 1-3
System
callsrequiringconnections
4-4
System
callsrequiringpaths 4-5
Systemdevice7-2
Systeminitializationerrorreporting7-3

T
Types of accessto directories

addentry4-10
change
entry4-10
delete 4-10
list 4-10
Typcsof aclessto files 4-10
append4-11
delete 4-10
read 4-11
updare4-11
Typicalnumberof objectscreatedby the EIOS during systemcall executionB-3

U
Use.IDs4-9
Userobjects4-9
Use.sanduserobjects4-8
UsiogoncbuîI€r\yithlheEIOSsystcm2-ó
Usingphysicalfiles 5-2
Usingprefl\esandsubpaths
together4-ó
Usingrandomaccess
devices
asphysicalfiles 5-1
volumes
formatting
5-1
implementing
yourownfile formar 5-l
usingvolumesformattedfor othersystems5-1
Usingtwo or morebufferswith the EIOSsystem2-6

lndex-4

Exteúded
I/O Use/s Guide

INDEX

v
VERIFY$USER systemcall 4-10
Volumes 3-1

ExtendedI/O Usefs Guide

Index-5

irÌt€l'
E X T E N D EiD
R MX@II

HUMAN INTERFACE
U S E R 'G
SU I D E

Intelcorpo.aton
Avenue
3065Bowers
5entaclara,Calfornìa95051

Copyrighto1988,IntelCorporation,All
R qhtsReserved

This manualdocumentsthe Human Interface,one of the layersof the Eltended jRMX II
OperaîingSystem.lt is intendedfor programmerswho wish to write applicatiol
programsthat can be load€dand executedvia keyboardcommands.This manualis
dividedinto the followingchapters:
Chapters1 and 2

Ovewiewof the Human Tnterfaceancldiscrrssion
of the command
line interpreter-

Chapters3
through6

Discussionsofthe four generalcategoriesof Human Interface
systemcallsand how to usethem when writing commands.
Descriptionof the necessary
elementsof a Human Interface
command,aswell as the requiredcompilationand bind sequences.

Chapter8

Descriptionof the configurableoptionsof the Human Interface.

Appendixes
A
andB

Listingsof type definitionsand string table tormat.

AppendixC

Listìngof the differencesbetweenthe iRMX II Release2 and the
iRMX 86 Release7 Human Interface.

Thismanualdoesnot describe
thecommands
suppliedwith theHumanInteriace.For
informationaboutthosecommands,
referto theOperator't
GuídeTo TheE te ded.RMX
II HumanInterface.

CONVENTIONS
This manualis intendedfor the personwho designsand implementsthe commands(the
paogrammer),not for the personwho invokesthe commandsat the tetminal. Whenever
this manualdescribeshow cerîainHuman Interfacefeaturesaffect the personthat
hvokes the commancls,
it refersto that personexplicitlyas the operator.
This manualusesthe followingnotationalconventionsto illustratesyntà(l
UPPERCASE

Tnexîmplesof systemcall syntax,ì.rppercase
informationmust be
qped as shown. The programmercan,however,enter this
infoamationin uppercaseor lowercase.

lowercase

In examplesof systemcall synîa\,lowercasefieldsindicate
informatìonto be suppliedby the programmer. The programmer
must enter the appropriatevalue or symbolfor lowercasefields.

lluman lnterfac€ Usefs Guide

lll

PREFACE

the OperatingSystem.This informationcan vary fiom messageto
message.
All numbers,unlessotherwisenoted,are assumedto be decimal. Hexadecimalnumbers
includethe "H" radix character(for example,oFFII).

RELATED
PUBLICATIONS
The followingmanualsprovideadditionalinformationthatmaybe helpfulto readersof
thismanual.
.

iRMX 286Netwo.kingSoftware
User'sGuide,OrderNumber:122323

i^PX 286UtilitiesUser'sGuide,OrderNumber:12193,1

HumanInterfaceUse/s Cuide

CHAPTER1

PAGE

CHAPTER2

PAGE

CHAPTER
3
COMMAND
PARSING

PAGE

ovERvlEw

Human Intefece Usedscuide

CONTENTS

CHAPTÉF4

r/o PRocEssrNG

PAGE

4.1 Overview...............
.................................4-1
4.2 Establishing
InputAnd OutputConnections.-.....-.-......................................................
4-1
4.2.1UsingC$GET$INPUT$CONNECTION.............................................................
4.2.2UsingC$GET$OUTPUT$CONNECTIoN........................................................4
4.2.3ExampleProgramScenario
..................
...........................4-2
4.3 Communicating
With The Operator's
Termina1..................................-.......................
4-3
4.4 FormattingMessages
BasedOn Exception
Codes......................................................
4-4
CHAPTER 5

PAGE

CHAPTER6

PAGE

CHAPTER7

PAGE

CHAPTER
8

PAGE

CONFIGUBATIONOF THE fIUMAN INTERFACE

HumanlnferfaceUser'sCuide

CONTENTS

APPENDIX
A
HUMANINTERFACE
TYPEDEFINITIONS
A . 1 T y p eD e f i n i t i o n s . . . . . . . . . . . . . . . .

APPENDIX
B

PAGE
. ........................................A-l

PAGE

Figure2-1. User Fxtension Example (Continued)...
2-6
Figure3-1.C$GETINPUT$PATHNAME
andC$cET$OUTPUT$PATHNAME
Example
3-8
Figure3-2.C$GET$PARAMETER
Examp1e.............................................................
14
Figure5-1. CommandConnection
Examples5-,1
Figure6-1.A CONTROL-C
Task8xamp1e................................................................
ó-4
FigureB-1.StringTableFormat..
..................................................8-l

Human Inlerfàce I lseÉs Guìde

CHAPTER
1
OVERVIEW

1,1 OVERVIEW
OF THE|RMX@
II HUMANINTEBFACE
The ExtendediRMX II Human Interfaceis a layerof the OperatingSystemihat allows
consoleoperatorsto executecommandson two levels:the standardcommandline
interpreterlevel (CLI) and the Human Tnterfacelevel (HI). When the Human Interfice
beginsrunning,it doesthe following.
r

Initiates a logon processthat validaîesoperators.On someterminals.this logon
processis invisible,becausethe terminalhasbeenpermanentlyassociated
with a
singleoperator. On other terminals(thosethat can be usedby many different
operators),the logon processinvolvestyping a logon nrme and î ptLssword
before
gainingaccessto the system.lf an error occursduring initialiation, the Human
Ì nl i n i t i a l i l . r l i o( n , , r .
I n t e r f a cgee n r r i r t c s i H

Createsan iRMX II job for eachoperatorloggedìnto rhe Human Tnterface.This job
(alsocalledthe interactivejob)furnishesthe applicationenvironmentwith commands
fo execute,

Assignsan area of memoryfor rhe operator(!his occurswhen the interactivejob is
created). Any commandsthat the operatorruns usethis area of memory. If there is
not enoughmemoryin the systemto initializean operittor,lhe systemassigns
whatevermemoryis availableat the time anciissuesa warningntessa.ge
to the
Iermrnal.

Startsan initial progràm(this alsooccúrs\À,hen
rhe inreraclivejobis created). The
initialprogam is the operator'sinterfaceto the OperaringSystenì.It is usuarrya
commandline interpreter(CLI), a programthat readsits instructionsfrom the
te.minal. The Human Interfacesuppliesa standardjnitialprogram which reads
commandsfrom the terminal and executesthe commandsbasedon lhat termìnal
input. Thesecommandscan either be CLI commands(suchasALIAS and
BACKGROUND) which are executedin the operator'sinteractivejob or Ht
commands(suchas COPY, FORMAT, and PASSWORD)which run as offspringjobs
ofthe operator'sìnteractivejob. You can alsosupplyyour own initial program. In
fact, therc can bc a separateinitial programfor eachuser.

Human Interface[Js€asGuid€

1-1

OVER\TEW

When an operatorentersinformationat a terminal,the operatorcommunicates
with the
initial program. With the standardinitial program,the operatorcan invoke a CLI
commandby enteringthe commandname(optionallyspeciryingparameters),or a HI
commandby specifying!he parhnameofÌhe file thar containsthe command(optionally
specifyingparameters).The initial programreadsthe informationfrom the terminal and
cxccutcsthc commands.If a HI commandhasbeenentered.the CLI invokesthe }Iuman
Interfacesystemcallsto load the commandinto main memoryftom secondarystorage,
createan iRMX IIjob for the command(as an offspringofthe operator'sinteractivejob),
and begincommandexecution.ff a CLI commandhasbeenentered,the CLI interprets
and executesthe commandwithin the CLI.
The Human Interfaceprovidesseveralfeaturesthat aid both operatorsand programmers.
Thesefeaturesilclude:
.

A set of Intel-suppliedcommands.

A group of systemcallsto aid programmersin writing their own commands.

A logon facilìtyto validateoperators.

A standardcomúand line interpreter(CLI) with its own set ofcommandssuchas
AIIAS, HISTORY. and SET.

Multi-accesssupport.

Supportfor wild-cardpathnames

1 . 2 R E S I D E N TH U M A NI N T E R F A C E
COMMANDS
In addition îo the residentHuman Interface,Intel suppliesa varietyof commandswhich
canbe usedwith any applicationsystemthat ilcludes the Human Interface. lncludedare:
.

CLI commands(suchas,\LI^S, HISTORY. SUBMIT, SUPER,and orhcrs)

File managementcommands(suchas COPY, DELETE, BACKUP, RESTORE,and
olners)

Device and volumemanagementcommands(suchas ATTACHDEVICE, FORMAT,
DISKVERIFY. and others)

GeneralUtility commands(srrchas DFBUG. DATE, and others)

T\e Operutor'sGuíde to tlrc EfiekdediRMX II Human Inteface confa;nscomplete
descriptiorsof all commandssuppliedwith the HumanInterface.

1,3 HUMANINTERFACE
SYSTEMCALLS
The Human Intedace providesa set of systemcallslhat programmerscan usein
commandstheywrite. The followingcategoriesof systemcallsare available:

t_t

Human Interfaceflser's Cuide

O}'ERvIEW

Command-parsing
systemcalls

l/O and messageprocessingsystemcalls

Command-processing
systemcalls

Programconlrol systemcall

The commandparsingsystemcallsprovidc thc ability to parserhe commandline, allowing
you to isolateand identi$,the parametersin a commandline. They alsoallow you to
determinethe commandnameand parseother buffersof text. Chapter3 providesfurther
discussionof the commandparsingsystemcalls.
The I/O and messageprocessingsystemcallsallowyou to establishconnectionsto input
and output files,communicatewith the terminal and format exceptioncodesinto a readyto-displayform. Chapter4 providesa further discussionof the I/O and message
processìngsystemcalls.
The commandprocessingsystemcallsallowyou to invoke interactiveHuman Interface
commandsprogrammatically.Chaptcr5 providcsa fr.rrtherdiscussionofthe command
processingsystemcalls.
The programcontrol systemcall allowsyou to overridethe defaultControl-C handling
task providedby the Human Intedace. Chapter6 describesthis in further detail.

1.4 LOGONFACILITY
Logon is the process that thc Human lnterface uses to vaìidate terminal operators. An
operator's view of the logon process diflèrs depending on how the terminal is confìgured.
Terminal ùsers can be configured in one oftwo {'ays: resident (or recovery resident) user
or nontesident user-

L4.1 Resident
User
The residentuseror recoveryresidentuser(whogainscontrolonlyif aninitialization
erroroccursin the configuration
Iiles)is definedduringsystemconfiguration.
All of its
attributesaredefinedin îhe HumanInterfacememoryduringtheconfiguration
process
andareloadedwith the system.A resìdentuserdoesnot useanyof the system
configuration
files.

1.4.2 Nonresident
User
A nonresidentuserand its terminalmust be definedin iRMX TTsystemconfigurationfiles
prior to systemexecution.Nonresidentuserterminalscan be configuredin one of two
ways:staticlogon terminalsor dl.namiclogon terminals.

HùnranlnterfaceUset'sGuide

t-3

oveRvrEw

1.4.2.1StaticLogonTerminals
Each staticlogon terminal is configuredto servicea specificoperatorwho can be either a
rcsidcnt or nonresidentuser. If the staticterminal hasa nonresidentuser.its attributes
are taken from the configurationfiles, :CONFIG:TERMINALS, :CONFlc:UDF, and
:CONFIG:USER/usernameduring!ogon(seeChapt€r4 in the Guí.leTo TheErtended
iR)lX II Intemctive Confguntion Utílít! for rnore information). Therefore, when the
Human Interfacestartsrunning,it hasinformationaboutthe operatorsuchas userID,
the amountof memoryavailableto this operator,and the priority. This meansthat the
logon processis automaticand invisibleto the operator. The only way to changerhe
Human Intedace'sassumptions
aboutstaticlogon terminalsis to changethe Operating
System'suserconfigurationfiles and restartthe OperatingSystem.

1.4.2.2Dynamic
LogonTerminals
Dvnamiclogon tefminalsare configuredto senice many different operatorson a requestby-reqùesthnsis To determ;ne\xhichoperatorwantsaccessto the Operat;ngSystemvia
a dynamiclogon terminal,the Human lnterfacerequestsinformationbefore allowingthe
operatorto accessthe system.This informationconsistsof a logon nameand a password.
The Human Interfaceverjfiesthat the informationenteredjs valid by checkinguser
configurationfiles set up by the systen manager.Then it setsup the terminalbasedon
the informationlisted in thosefiles.
Unlike sta(icterminals,dynamiclogonterminalshavedvnamicmemorvpartitions. Thaî
is, the Human lnterfacedoesnot assignany memoryto the terminal at systemstartup.
lnsteîd, it assignsthe memorywhen an operatorlogson. Thc amountassignedvaries
dependingon the operator'srequirements(as listed in one of the configurationfiles).
The advantageof dynamic-partitionîerminalsjs that the memoryavailableto operators
variesdependingon the needsof the operator.
When the operatorlogsoff a dynamiclogonterminal,the memorygoesbackinto the
generalfree spacepool. However,if there is no liee spaceleft in the system,an operator
won't be ableto logon.
'flrc

Guide To The Ertud&I ifttLr II Interactir)eCanfguration Urlllo, describeshow ro ser up
staticand dynamiclogonterminalswith staticand dynamicmemorypartitions,
respectively.

1.4.2.3NetworkAccess
lf theiRMXlI system
issetupasa workstaîion
onaniRMX-NETcommunications
network,any operatorwho logsonto the systemon a dynamiclogon terminal
automaticallybecomesa verified userof the network and can accessremotefiles via the
iRMX-NET network. Refer ro the IRMXNeL*-orkSot--arelJter'sGuide foî more
informalionaboutthe iRMX NET environment.

l-4

HumanInterfaaeUser'sCuide

OVERI'IEW

1.4.2.4 LoggingOft
When operatorsof dynamiclogon terminalsfinish accessing
tlì€ OperarirìgSysrem,they
can usethe LOGOFF commandto terminatetheir sessions.Other operatorscan then log
onto the sameterminals.

1.5 STANDARD
INITIALPROGRAM
Oncean operatorlogs onto the Human lnterface,the Human Interfaceassimsan initial
programto the operaîor. This initial programis lhe first proUram to run. The identity of
this initial programis determinedby a privilegedoperator(normaltycalÌedthe system
manager)when addingnew usersto the system.This processjs d es$lbedin theExtend.ed.
|RMX II Inteructíve Confrgurction Utitity Refere ce Manuat .
Aìthough the iniîial programcan be almostanythìng- from an editor ro a Basic
interpreter- the Human Interfacesuppliesa standardìnitialprogram calledthe Human
Intedace CommandLine Inte.preter (CLl). Ifyou haveusedRelease1 oithe iRMX II
OperatingSystem(which is still available),norethat the CLI suppliedwith Release2 has
beenenhancedto includemanynew features. The function of the Humîn lnterfaceCLI
is to read input from the terminal,allowingthe operatorto edit that input ifnecessary,
and executecommands(either CLI or HT) basedon the input. The CLI providesa
numberofadditional featuressuchas aUasjng.hrckgrounjprocersing,anJ recallingol
prevìouslyenteredcommandlines. Chapter2 discusses
the standardCLI in further
dctail.

1.6 MULTI-ACCESS
SUPPORT
TheBasicI/O Systemsupportsmultipleterminaìs
byprovidingdevicedriversthat
communicate
with multiple-terminal
hardware.TheHumanlnteriàceaddsto this
supportby providingidentification
andprotectionof usersbasedon logonnamesanduser
IDs. Thissupportis calledmulti-access
support.
With mulîi-access
support,multipleoperators
cancommunicare
with theOperating
System.At lo8on,the F{umanInterfaceassociates
eîch operatorwith an idcntification
calleda user lD, and assignseachoperatora separatearea of memoryin which to run
commands.When an operatorcreatesfiles or attachesdevices,the Human Interface
marksthe operaîoras the ownerof thosefiles or devices.Accessto the liles by other
usersdependson the permissiongrantedthoseusersby the owner. The multi-access
Human Interfacealsoprovidesthe operatorthe capabilityto executecommands,run
developmentprograms(like editors,compilers,and so on), and run other application
orosrams.

HurnanInterfaceUsefs Guide

OVER\TEW

To run a multi-accessHuman Interface,the systemmanagermust fùst set up the proper
directorystructureand provide severalfiles containinginformationaboutthe operators
that can accessthe system.However,you can still tailor your systemto meet your
individualneedslry selecti[8,for eachoperator,the inilial programthal runs when that
operatoraclessesthe Human Interface. You can choosethe standardCLI (suppliedwith
the Human Interface)or a customizedinitialprogram. Thc uscr dcscriptionfiles
maintainedby the systemmanageridentifythis choiceto the Human Interface. This
process is described in the Eúended iRMX II Interaúive Confgìrration LltílítyReÍerence
Manual.
Programmerswho write commandsdo not haveto write their codedifferentlyfoa a multiaccessHuman Interfacethan for a single-acr:ess
Human Interface. The only differencea
commandmight eÀ?erience
in a multi-access
environmentthat it wouldn't experiencein a
single-access
environmentinvolvesaccessiÌtg
files and devices.When a commandis
iovokedby àn op€rat(rr,the commandinheritsthe opera!or'suserID. Thus,the
commandcanperform operationsonly on files and d€vicesto which the invokingoperator
has access,In a multi nccesseîvironmcnt, a commandmisht not be ableto accessaÌl the
îiles or devicesit wantsto access.

1.7 WILD-CARD
PATHNAMES
The Human Interfacesupportsthe useofwild-card charactersin file names. This gives
lhe operatora shorthandmethodofspeciryingseveralfiles in a singlereièrence.The
wild-cardcharacterssupportedby ihe Human Interfaceare
?

Matchesany singlecharacter

Matchesany sequenceofcharacters(includingno characters)

The Operator'sGuide To The Exle ded,íRMX II Human Inteface describeshow an
operatorcan usewild-cardcharacterswhen enteringcommands.
Programmerswho write îheir own Human Interfacecommandsdo not haveto provide
specialcodeto supportwild card pathnamcsas long as they userhe Hùman Interface
systemcallsC$GET$INPUT$PATHNAME and C$GET$OUTpUT$PATTINAMEto
obtain the file namesfrom the commandline. The Human lnterfacecontainsthe
mechanismto interpret the wild cardsand return the correctfile nameto the calljng
command. Refer to Chapter3 for more informationaboutthesesystemctlls_

t-ó

Human Infeface Use s Guide

2,1 INTRODUCTION
A CommandLine Interpreterprovidesan interfacebetweenthe operator'sterminal and
the OperatingSystem.The CommandLine Interpreteris usuallythe meansfor executing
Human Interfacecommands,but it canbe almostan).thingfrom a Basicinte.preter to an
editor. The CommandLine lnterpreter is the operator'sinitial program. l he Human
lnterfacesuppìiesa standardinitìal programcalledthe Human InterfaceCommandLine
Inte.preter (CLI). When invokedthe CLI providcsthe opcratorwith line-editingand
aliasfacilities,backgroundprocessjng,
sessionhistory,terminal definition and execution
of its own set of commands.The Human Interfacecan alsooperateÌvith a user extension,
which allowsyou to add customizedfeaturesto the standardCLI, or with a customized
CLI. This chapterexplainsthe featuresand useof the standardCLT,expìainshow to
incorporateuserextensions,
and lists the rulesfor writing a customizedCLI.

2.2 CLIFEATURES
The Release2 Human InterfaceCLI providesa numberoffeatures that make it a useful
tool in a developmentenvironment.They are listedhefe with a brief descrìption.
Line-editing

Allows operatorto re-edit input-

Aliasirg

Allows the operatorto abbreviatecommonlyusedcommandsand
assignparametersto them. For example,the operatormay define;
ALIAS PLM = :I-ANG:PLM286
Then when the operatorentersPLM A.28, the CLI executes
:IANG:PLM286 A.28
Alias expandingcan be repeatedup to five times for easeofuse.
An exampleof reiterativeexpansionis:
ALIAS PLM = :IANG:PLM2Só
ALIAS PNL=PLM #0.P28NoLTST
When the operatorenters:PNL SOURCE, fhe CLI
execules:
:l.ANG:PLM286 SOURCE.P28NOLIST

HumanInterfaceUser'sCuide

THE COMMAND LINE INTERPRETER

Background
processirìg

while
envi.onment
Allowsth€ operatorto runjobsin a background
at theterminal.The operatoris
continuingto invokecommands
notifiedwhena backgroundjob
is startedandwhenit finishes.Itis
possible
or cancela
to requesta list of theactivebackFoundjobs
backgroundjob.

Session
history

Displaysthelast40commands
andallowstheoperatorto select
linesfor re-editing.

I/O redirection

other
Allowsstandardinputandoutputto be directedsomewhere
thanthe operator's
terminai.

Set

Allowsthe operatorto performonline changes
to certainCLI
attributes such as, the prompt and the background memory pool

size.
The implementationof thesefeaturesis possiblewith the followingset of CLI commands:
ALIAS, BACKGROUN'D, DEALIAS, HISTORY, JOBS,KILL, LOGOFF, SET'
SUBMIT, and SUPER. All of the CLI commandsare describedin defatlin fhe Operator's
Guile To The Ertenderl íRMX II Human Interface. If the standartj CLI satisfies the needs
ofyour application,you can assignit to eachoperatoras an initial program.

2.3 INITIALIZATION
The Human Intedace CLI can be invokedduring either staticor dynamìclogon. During
initialization,the Human InterfaceCLI performsthe followingoperations:
.

lnitializesthe CLI environment

CallsCLI e\tensions,
if necessary

Displaysa sign-onmessage

Createsan iRMX II objectcalleda commandconnectionin which it places
informationreceivedfrom the terminal. Refer to Chapter5 for more information
aboutcommandconnections.

Attachesor crealcsthe operator's:PROG: directory

Submitsthe file :PROG:R?LOGONfo. processing

After this initial processing,the CLI displaysthe Human Interfacedelaultprompt (-) and
readsiopul lrom thc t€rmirlal. Input Irom the terminalcan be a CLI command,a Human
Interfacecommand,or a user applicationprogramthat is to be executed.

HumanInterfaceUser'sGuide

THE COM\,IANDLINE INTERPR.ETER

2.4 COMMANDINVOCATION
The CLI beginsexecutingthe commandeither after a carriagereturn or an ESCAIE has
beenenter€d. However,before execution,the CLI allowsthe operatorto edit the input
lile or recallpreviouslyenteredlines When input is rerminated,the CLI performsthe
followingoperationsl
.

readsthe commandLineîrom the tefntinal into a CLI buffer

expandsall aliases

handlesany I/O redirectionthat may be necessary

passescontrol to the userextensionprocedureCllgusergprocess,if applcable (see
sectionon userextensionslater il this chapter)

searchesfor CLI commands(suchas ALIAS, HISTORY, SET), or HI commands
(suchas COPY, DISKVERIFY, FORMAT).

li the CLI encountersa CLI command,it parsesthe commandwithin the CLIjob,
executesthe action requested,and ifncccssary,caìlsthc lluman lnterface systemca
C$SEND$COMMAND to continuethe processing.If the CLI encountersa HI command
or any userapplimtion p.ogram,it placesthe informationit readsinto the command
connection(usingthe Human IntedacecommandC$SEND$COMMAND). After
receivinga completecommand,the commandconnectionhandler:
.

Removesthe commandnameportion

Loadsthe file containingthe command

Passesthe parametersto the command-

It may be necessary
to conthue an HI commandbecauseof its lengthor sirnplyfor easein
understanding.In this case,the CLI recognizesthe ampersand(&) mark at the end ofa
commandline as a continuationcharacter,and displaysa doubleasterìsk(**) on the
continuationline.
It is possiblefor the operatorto recîll cithcr thc complcrecontinuationline or only part
of it. A doubleasteriskappearson the screento indicatethat a continuationline is being
recalled.The operrtor can then e.iit the relevantsectionofthe line. However,after the
sectionhasbeen edited,the entire commandline is executed.For an example,see
Chapter 3 of the Operator'sGuide To The Ertended IRMX II Human Intelace.
The CLI displayserror messages
for eachcommandin the eventofcertain operator
errors. For a completedescriptionofthe CLI error messages,
seethe detailed
expÌanationof eachCLI commandgivenin the Operator'sGuideTo TheExtended|RMX II
Hunnn Inteíace .

Human InterfaceUsefs Guide

2-3

TIIE COMMAND LINE INTERPRETER

2.5 USEBEXTENSIONS
The Human InterfaceCLI can be erlendedto includecustomizedfunctions. With this
feature,you can ùeate an initial programthat takesadvantageof the standardCLI
features,suchas line-editingand aliasing,and still meetsyour preciseneeds. The
proceduresthat you add to the standardCLI to be ableto parsecommandsdifferentlyor
implementyouÍ own commandsare calledCLI userextensions.
This sectionexplainshow
ro extendthe CLI to ineludeuserextensions.

2.5.1CreatingUserExtensions
Creatinga userextensioninvolveswriting three procedures:an initiaìizationproceoure,a
processingprocedure,and an epilogueprocedure.Theseprocedures,describedin the
followingsections,can be combinedinto one module. Intel suppliesan empty default
modulecalledHCLUSR.P2S(locatedin :SD:RMX286/HI) whjch providesyou with null
insîancesof the three procedures.The Human InterfaceCLI hasthree entry points to
the userextensions,one beforeeachprocedure.
2.5.1.1 Initialization
When the CLI is initializedit first definesits own aliastables(the memoryareawhere
userdeiined aliasesare stored)and data structures-It then callsthe usersupplìed
initial;ation procedure.Ifyou havetablesor datastructuresto add during initialìzation,
they shouldbe part of the initializationprocedure.This procedureis calledonly once
during CLI initialization. The CLI entersthe userextensionby calling:
C A L LC L I 9 U S E R $ I N T T ( " \ c e prt )$ ;p t
You can bind this procedureto the CLI library suppliedwith the Human Interface. An
erampleof how to do this is givenlater in this secrion

2.5.1.2Proc*sing
Aftereachcommand
line(entered
eitherfroma terminalor in a SUBMITfile),theCLI
translatesall aliases,and checksagainlbr userextensions.At this point, you can changea
command,perform additionalfunctionsbefore execution,or processthe command. To
accessyour user€xteDsion,
the CLI calls:
cont$flag

CLISUSER$PROCESS(comand$ptr, èr.eptSpir)

;

where:
command$ptr

a pointerto a STRINGcontaining
theexpanded
aliascommand
readvfor execution

HumanlnterfaceUser'sGuide

THE COM\{ANDLI NE INTERPR,ETER

cont$flag

a b)4€indicating
whethertheCLI shouldcontinueexecuting
the
command
line modiliedbythe userext€nsion,
or ignoreit and
continueto theusercxlcnsi{rn
epilogueprocedure-

2.5-f-3Epilogue
Whenthe CLI hasexecuted
a command(HI command,
CLI command,
or usersupplied
command),
it callsthe epilogueprocedure.Thisprocedure
can handleerrorconditions
or performanyoîherfunctionsthatcannotbeperformeduntil thecommandhasbeen
executed.Theepilogueprocedure
is calledby:
CALL CLI$USER$EPILOG(excepr$prr);
Thisprocedr.rre
canbe boundto theHumanInterfaceCLI libraryasshownin theexample
givenlaterin thissection.
2.5.1.4ErrorHandling
Eachof the threeuserextension
proceduaes
retuansan earorcodein theexceptiori
pointer,except$ptr.lf theprocedure
returnsanythingotherthanE$OK,the CLI outputs
an errormessage
in additionto themessage
issuedby C$SEND$COMMAND
or the CLI
command.
The CLI catalogsthe error codegeneratedby the last commandunder the name
R?ERROR in the globaldirectorybeforeexecutingthe user epilo$re procedure. Yoù
can accessthis value and useit in your application.However,any changesto R?ERROR
are not recognìzedby the CLI. The followingcodeenablesyou to accessthe valuein
R?ERROR.
DECIARE
error$È

TOKEN,
BASEDerror$r UORD,
except
woRD;
e r r o r $ r = R Q $ L o O K U P $ o B J( S
EE
cT
L E C T O R $ 0 F ( N(l 3
L () 7
, ,,R?ERROR,),0,eexcept);
AJter executionof this systemcall,effor will containthe error codethat the last command
sert to R?ERROR.

2.5.1.5A SampleUserExtension
Thefollowing
example
shows
howto createa userext€nsion
usingthethreeprocedures
describedabove. The userextensionillustratedhere aììowsyou to measurethe time
requiredto executea CLI command,an HI command,or any apptcationprogram. The
codeshownhere is a straightforwardexample.Many specìalcaseshavebeenomitted.

Humanlnaerface
User'sGuide

t_<

THE COMMAND LINE INTERPRETER

**********************

/*************:t**********)t*********
TITLEt

lRìfi Il CLI user exrension example : TIMER

ABSTRACÎ:
A11o\r the user to neasure tine required
comaDd or any applicalioÌì pro8rau.

to execute a CLI

USAGE:
-T
uhèrF

.òmm:nrl

lÀ

rnv

coùìnand

llne

rhar

che

ÍRMX II

CLI

*********5r**************:r*:t*:t*:!*:!***r!***+***************/

H C L U S RD
: O;
/*
DECIARE
CR
LF
TOKEN
STRING

Elob^l declarations

'ODH'
'OA}|'
'SELECTOR"
' STRUCTURE
(

LITEMLLY
LTTERALLY
I-ITERALLY
L]TERALLY

length
chat(1)
/*
9include
9 include
$ inc lude

include

files

BYTE,
BYIE)' ;

( /rmx2 86linclerror . lir)
( /rmx2 86/inclb ios . exr)
( /rnx2 86/incle ios . ext)

externals

cÒnvert$dw9dècina r :

x/
PRocEDURE(destinarion$p, de s tinerion$nax,
dw$nunber, length, excep$p ) EXTERNAL;

DECIARE
destinaclon9p
POINTER,
destination$nax WoRD
,
du$nunber
DtJoRD,
length
I,IORD,
excep$p
PoINTER;
END conver tSdw$decimal ;

Figure2-1. UserExtension
Example(Continued)

2-6

HumanInterfaceUset'sGuide

THE COMMANDLINE INTER}RETER

DECIARE
BOOLEAN
rALSE
TRÙE
usersco9t
no$co
tine!
tine

LITERALLY ' B\"IE'
I,ITERALLY 'O' ,
LTTERALLY 'OFzu'
ToKEN,
BooLEAN,
BOOLEAN,
DWORD;

'CLI9User$lnit'
9subtitle (
)
/*********************************:!**************************)t*************

îITLE:

Cr.T$llser$Init

CALLINGSEQUENCE:
C A L Lc L I $ u s e r $ l n i t ( e x c e p $ p ) ;
ABSTMCT:
The iRÌ.fX II CLI cal1s lhis procedure ar
initialization,
ro allo', the user ro inirialize
data stnrctures and variables
ALGORITTiì'I:
atlach
signal

and open a connectlon to :COl
(N09co flas) íf it was opened successfully

**********************************************************r!***)t*5t****:!*)r**//

( excep$p) REENTRANTPUBLIC;
PROCEDURE

CLI9userglnit:

DECI-ARE
excep$p P0INTER,
excep
BASED excepgp lioRD;
excep : E$oK;
no$co - FALSE;
user$coqt - rq$sSattach$file( @(4,,:c0: ,), excep9p);
IF excep - ESOKTHEN
C A L Lr q $ s $ o p e n ( u s e r g c o g t , 3 , 0 , e x c e p g p ) ;
lF excep .> E$OKTHEN
nogco - TRUE;
RETURN;
E N Dc L I $ U s e r $ l n l È ;

Figute 2.1. User ExtensionExample(Continued)

Human Interfacel]ser's Guide

THE COMMAND I,INE INTERPRF]TT]R

9 s u b t i t l e ( I C L I $ U s e r 9 P r o c è s s) '
/****************
TITLE:

Cl-I$UsèrSProcess

CAIL]NC SEQUENCE:
continue - CLI$User$Process(conn$bufgp, excep$p) ;
ABSTMCT:

The iRl,lx II CLI ca1ls this procedure before executing
a conmand line, but after line-ediling
and alias
replacenenc, Èo al1ow corunandmanipularlon.
If rhe CLT
is to continue processingJ thís procedure returns TRUE. If
FALSE is returned, the CLI skips this comÌand and cal1s
the cLI$user$epilog,

ALGORIÎHM:
I F - L o r - T i s F o u n d i n t h e c o f l m " n dl i n € T H E N
DO;
get lhe system time;
remove r-t'
fron the conmand líne
se! tirìer - TRUE for use by the Cllguser$epilog
END;
Tell

the CLI to continue processing RETURN(TRUE)

*******:l**********:r***:r*******:!**********:!*:t*:r.***:!***:!*:!*:!****,t***********/

CLI9user9Process:

PRoCEDURE
( conÌn$buf$p, excepgp) BYTE REENTRANT
PUBLIC;

DECI,ARE
conm$buf$p
comn$buf
excep$p
excep
DECLARE
index

PoINTER,
BASED
P0INTER,
BASED

corùr$buf$p STRINC,
excep$p

WORD;

Ì,IoRD;

excep : E90K;
lF no9co
THENRETLTRN(TRUE);
- 0;
line
riner = FALSE;
Figure 2-1. User Extension Exampl€ (Continued)

t_r

Human Int€ aceUsefs Guide

THE COMMANDLTNETI\TERPRETER

'-t' */
/* search fot
índcx
F1NDB(lacom$buf. char, , ,, comgbuf.lenrrh);
IF index a oFFFFH THEN
DO;
IF comÍìgbuf.char ( index + 1) - ,T, oR
comÌ$buf char(inde). + 1) : ,r, THEN
DO;
'-t'
fron the conurand*/
/* remove
conn$buf . chat ( index) , conm$buf.char( index + l) E i n e - r q 9 g e t $ t i m e ( e x c e p $ p );
lF excep = E$oK THEN
tirìer : TRUE;
END;
END; /* direct CLT to continuc comand processing*/
RETURN(TRUE)
;

E N Dc L I $ U s e r $ P r o c e s s ;

'CLI$UserSEpiLos'
$subtitle (
)
/*********************)y************:t******************ìt*ìt*****:t**ìt*ìt*ì!*ìt*ìt*
TITLET
CLI$user$Ep11og
CALLINGSEQUENCE:
C A L L c L I g U s e r S E p i l o g ( e x c e p g p;)
ABSTRACT: The iRMX 1I CLI ca1ls rhis procedure afcer execucing a
comand line to perforn comànd épilogue functions.
ALGORITHM:
]
lF there is no connection to :CO: or no timer needed for
this comand THEN RETURN
.alculate Lhe rime elapsed sin.e CLI$user$pLocess
wr:ite rhe tine message to the screen;
*****************:l************+***:!*:t*:!*:f***)9*********)L*******************/

cLI9UserSEpilog:
DECIARE
excep$p
excep

( excep$p) REENTRAIT PUBLIC;
PRoCEDURE

POINTER,
BASEDexcep$p l,lORD;
Figùre 2-1. User Extension Example (Continued)

Human Inaerf.ceUset's Guide

2.9

THE COMMAND LINE INTERPRETER

DECI-ARE
actual
cincgstr

itoRD,
STRUCTL'RE(
length
char(14)

exceP : E9OK;
IF nogco OR NOî tiner
RETURN;

BYTE,
BYTE);

THEN

tine$str. Iength - 0;
/* calculate rhe elapsed cine */
=
Eine
rq$getStine(excepqp) - tine;
TF excèp o ESOKTHEN
RETURN;
C A L Lc o n v e r t $ d u s d e c ' n d( l @ ti m e S s ' r , s l z E l r i m F $ . t r ) , L i m e ,
STzE(tirìègstr) - 2 , excepgp);
IF excep = E$oK THEN
DO;
a c t u a l : r q S s $ \ ' r r i t e $ m o v e ( u s e r $ c o $ t@
, ( ' E r a p s e dr i m e : ' ) ,
14, excep$p);
lF excep = E$oK THEN
actuar - rq$sqvrite$nove( user$co$c, @tinìe9srr.char,
t i n e q s t r . l e n g t h , e r c e p $ p );
IF excep : E$oK îHEN
accual
rq$S$u!iLe$move/Lser$co@
$ r l, s e c o n d s ' , c R , L r r ,
10, excepgp);
END;
RETURN;
END Cl-lSUsetSepilog;
END HCLUSR;

Figure 2-1.Uscr ExtcnsionExample

2.5.2BindingA UserExtension
To useyoùr userextension,bind it to the Human InterfaceCLI Libraryusingthe
procedureshownbelow.(It is rccommenclecl
that you combinethe three proceduresinto
one module,but this is not necessary.)lfyou havecalledthe usereltensionmodule
MYEXT.P28,you can usethis exampleexactlyas it is writtcn. Othcrwise,replace
MYEXT.OBJ with the nameof the obiectmodulevou wish to bind.

2-10

HumanInterfaceUse/s Guide

THE COMTIANDLINE INTERPR,ETER

: LANG:BND286 &
MYLXT.OBJ, &
/Ryx286 /Hr /HCLI .LrB (HCLI ) , &

/Rv,x286/Hr /HCLI.LrB, &
/Rt'tx286/HI /Hf .LrB , &
/RMX286/LIBlRrtr{r FC. LtB, e
86IHIIHUTIL. LIB, &
/RMX2
: IANG:Pl,l'f286. LIB &
RENAMESEG(CODE
TO CLI CODE,DATA
TO HT DATA,HICODF,
TO CLI CODE,
HI DATATO CLI DATA)
&
OBJECT(MYCLÌ)
NOLOAD
NODEBUC
SECSIZE(STACK(2400H)
) &
( I0000,0FFFFH)
RC( Dl.r
)

MYCLI

is thenameyouuseto invokethisCLI. For a complete
explanation
ofthe parameters,
seeChapterT ot thismanual.

Bindingyour extensionsas shownabovccrcatesa lluman IntcrfaceCLI with your user
extension.Ttris nculy credredCLI canrhenbec.rlJc,J
by it. paLhnrme.
MYCú|. rr a
nonresidentCLI duringthe logonprocess-Ifyou want the default residentCLI to include
userextensions,
you shouldspecii, the pathnameof the userextensionmoduleduring
configuration.For more information seethe Ertended.
.RMX II InteructiveConfiwmtion
UtíIíE RefercnceManual.

2.6 CUSTOMIZED
INITIAL
PROGRAM
If the standardiniliíl programor the standardinitial programas modifiedby a user
extensiondoesnot meetyour needs,you havcthc option ofproviding your own initial
program. The initial programmay be similar to the Human InrerfaceCLI, or it may be a
completelydifferent kind of program For example,you couldwrite a CLI that allows
accessto liles in selecteddiectorìes only. This would preventan operatorfrom
accidentallymodifyingother files. Or if you want a particLrlaroperatorro use only Basiclanguageprograms,a Basicinterpretermight be the inirial programfor that operaror.
You can selectthe inilial programfor eachoperator. For example,you may continue
usingthe iRMX II Release1 CLI as the initial program. To do rhis,you simplyspeciry
your selectionin the userdescriptionfiles maintainedby the systemmanager(refer to the
Ettended íRMX II InteructtueConfiguration UtinryReferenceManual).
Ifyou providc your own initial program,the programmust obeythc folowìng rulÈs:
.

It must initializeits owrìdata segment.The Human Inlerfacedoesnot set the DS
registerfor the CLL

It must perform input and output via logicalnames:CI: and :CO:.

Human Interface flse/s Guide

2-11

TIIE COMMAND I,INE INTERPRETER

Ilit requùesthe ability to run Human lnterfacecommands,it must createan iRMX II
objectcalleda commandconnection(via the
C$CREATE$COMMAND$CONNECTION systemcall). If the initial programdoes
nol createa commandconnection,it (and any other applicationtasks)cannotusethe
followingHuman Interfacesystemcalls:
C$CETSINPUT$PATHNAME
CSCET$OUTPUT$PATHNAME
C$GET$INPUT$CONNBCTION
C$GET$OUTPUT$CONNECTION
C$SEND$CO$RESPONSE
C$SEND$EO$RESPONSE
C$SEND$COMMAND
C$SET$CONTROL$C
CSDELETESCOMMANDSCONNECTION

If it doesn'tcreatea commandconnectionbut still wishesto usethe Human Intedace
syst€mcallsC$GET$PARAMETER, C$CET$CHAR, and C$BACKUP$CIIAR, it
must first invoke the C$SET$PARSE$BUFFERsystemcall.

It must invoke the ExtendedI/O Systemcall EXIT$IO$JOB to terminateprocessing.
It must not usethe PL/M-286 or ASM286 RETURN statementfor this purpose.

Refet to the E tendediRtrlX II Hufian Inteface SystemCaIk ReferenceManual for
detaileddescriptionsof th€ Human InterfscesystemcaÌlsmentionedin this section.
Refer to the iRMX /1 Er.tendedI/O SystemCalLtReferc ce Manual for information about
the EXIT$IO$JoB systemcall.

HumanInterfaceUsertsGuide

3.1 oVERV|EW
Wheneveran operatorentersa HumanInterfacecommand
from theterminal,an initial
progmmassociated
with thatoperatorreadstheinformationandcauses
the Operating
Systemto invokethecommand.Whenit invokesthecommand,
the OperatingSystem
placesthe paramerers
into a parsingbuff€r. Oneof the firstthingsthatthecommand
mustdo is to readthe parsingbuffer,breakthecommandline into individualparameters,
and determine the correct action to take based on the nurÌtbet and meanins oî rhe

parameters.

NOTE
The Humanlnterfacesuppliedinitialprogramreadsa commandand
determincs
ifi! is a CLI or a HI command
beforeelecuringir. CLI
commands
arehandleddifferentlythanHl commands.
Thischapterdeals
only with HI comúand parsing.
The Human Interfaceprovidesseveralsystemcallsto parsecommandlines that folìow a
standardstructure. It alsoprovidesother systemcallsto processnonstandardformats.
This chapterl
.

Definesthe standardstrùctureofcommandlines

Describesthe systemcallsusedto parsecommandshavingthis structure

Discusseshow to switchfrom one parsinglruffet to anotherparsingbuffer

Describessystemcallsyou can useto parsenonstandardcommands

Describesa systemcall that you can useto obtainthe commandnamethe operator
usedwhen invokingthe command

3.2 STANDARD
COMMAND-LINE
STRUCTURE
The staÍdard structureof a Human Interfacecommandline consistsof a numberof
elementsseparatedby spaces.It is recommendedthat your commaodsfollow this
structureto enableparsingby the Human Interfacesysîemcalls. However,if you require
a different structure,refer to the "ParsingNonsîandardCommandLines" sectionofthis
chapter.

Human InterfaceUsels Cuide

3-1

COI\fMANI) PARSING

The standardstructureis as follows(squarebràckets0 indicateoptionalportions)l
command-nameIinpathlist [prepositionoutpathlist]l lparameters]
where:
command-name

Pathnameof thc file conlainingthe command'scxelulableobj€cl
code. The pathnamemay consistof a prelix and a subpath.A
prefix is a logicalnameof a directoryand is uniqueifit is not
duplicatedin one of the dire,ctories
in the commandsearch
sequencedefinedduringconfigùration Seethe Ertcndcd|RMX
Inteructive ConfrgurutionUtility RefercnceMafiral for more details
on directories,prefixesand logicalnames.

inpath-list

One or more pathnames,separatedby commas,of files that the
Human Interfacereadsas input during commandexecution.
Individualpathnamescan containwild-cardcharactersto signiry
muìtipleîiles- Refer to the Op?mlorìîGuide To The F.xtcnded
|RMX Il Human Intetfacefor a descriptionof the wild-card
charactersand their usage.You can use the
C$CET$INPUT$PATIìNAME systerncall io processthis inpathllsL

preposition

A wordthattellstheHumanInterfacehowto handlethe output.
Thestandardstructuresupportsthefollowingprepositions:
TO

TheHumanlnterfacewritesthe outputto a newfile

indicatedby the output pathname. If the file al.eadyexists,the
Human Interfacequeriesthe operatoras follows:
< parhname>, alreadyexists,ovERwRITE?
If the operatorentersa Y or an R (uppcrcaseor lowercase),the
Human Int€rfaceoverwritesany informaîionin the existingfjle
with the new output. (An R tells the Human Interfaceto continue
overwritingexistingliles without promptinglbr permission.)Any
other charactercausesthe Human Intedace to proceedwith the
next pair of input and output files.
OVER
The Human Inter{acewrites the output to the file
ìndicatedby the output pathnxme. lt overwritesany information
that currentlyexistsìn the fileAFfER
The Human lnterfaceappendsthe output to the
end of the file indicatedby the output pathname.
You can use the C$GET$OUTPUT$PATHNAME systemcall to
processthe prepositìon.

HumanInterfaceUser'sGuide

COMMANDPARSING

outpath-list

Onc or more pathnamcs,s€paratedby comnas, of lìles that are to
receivethe output duringcommandexecution.The total number
ofpathnamesin this list and the numberofwild,cardsusect
dependson the inpathlist. Refer to the Opdrdtor'sGuide To The
Extended|RMX II mtma l tefuce îor more information. You can
usethe C$cET$OUTPUT$PATHNAME systemcall to process
the outpathJist.

parameters

Paraúetersthat causethe commandto perform additionalor
extendedservicesduringcommandexecution.The standard
structuresupportsparameterswith the followingformats:

value-list

The parameterconsistssolelyof one or more groupsof characters
(calledvalues)separatedby commas. When the value-listis
presentin the commandline, the commandperfornìsthe service
indicatedby the values.

keyword=value-list A key$'ordwith an associated
value (or list ofvalues,separaîedby
commas).The kelvord portion identiliesthe kind of serviceto
perlorm, and eachvaluesuppÌiesfurther informationaboutlhe
seryicerequest.
ke)$/ord(valueJist) Alternate form of the previousformat.
kelnrr'ord
value-list

A kelavordwith an associated
value (or list ofvaìLres,separatedby
commas).Lìke the previoustwo formats,the kelvord portìon
identitiesthe kind of serviceto perform and eachvalueportion
providesmore informationaboutthe service.However,the
kelvord mustbe identifiedto the commandas a prepositìon(refer
to the descriptionof the C$GET$PARAMETER systemcall in rhe
Ex.tendediRMX II Hutuan Interlace S]'.Jtem
Calh ReferctrceMunlutl
for more information). You usethe C$GET$PARAMETER
systemcall to processthe parameter.

Line terminatorcharacterThe RETURN (or CARRIAGE
RETURN) key and NEW LINE (rr LINE FEED) key are both
line terminators.

The followingexamplcsshowhow you shouldellter all Human InterfacecoÙrrnandusin8
the commandstructuredescribedabove.
caPY /rnx286/fílel
TO /rù-/rik2

FORMAT
:f0: FILES-300GRANULARITY-200
BS
UPCOPY
:f1:nyfile T0 /ne',',dirloutfile Q
For morc cxampÌcsscrjthe Opemtot'sGuAe To TIE Ertended íRMX II Ilut útl It teface.
The Human Interfaceaìsosupportsthe follo\À'ing
speciaìchrrrcters:

Hùman lnterface User'sGuide

3-3

CONIMANDPARSING

coniinualion
character

An ampersandcharacter(&). When an operatorincludesan
ampersandin the commandline as the last characterbeforethe
line terminator,the HLrmanInterfaceassumesthat the command
irvc'catiorìcorìtinueson the nextline. If the standardHuman
Interfacecommandline interpreter(or any customcommandline
interpreterthat usesC$SEND$COMI,L{ND to jnvokecommands)
processes
the operator'scommandentry,îhe ampersand(and the
line termjnatorthat follows)are edjtedout of the parsingbuffer.
Then the continuationline is read and appendedto the parsing
buflèr. This processcontjnuesuntil the operatorentersa line
termjnatedby a carriagereturn without a continuationcharacter.
Therefore,when the commandreceivescontrol, its parsingbuffer
containsa singìecommandinvocatìon,without intermediate
continuation
characters
or lineterminators.

NOTE
CLI commandssìrchas ALIAS, SUBMIT and SUPER do not recognize
continuationcharacters.However,continuationcharactersare recognized
by all human Interfac€commandsfound jn :SYSTEM:.
commenlcnaracler

A semicolon
character
(;). TheHumanInterfaceconsiders
this
charactcrand all tcxt that followsit on a line to be a nonexecutablecomment. lf the standardHuman Interfacecommand
line interpreter(or any customcommandline ìnterpreterthat Lrses
C$SEND$COMMAND to invoke commands)processesthe
operator'scommandentry,all commentsare editedout of the
parsingbuffer. Therefore,individualcommandsdo not haveto
searchfor andd;scardcomments.

3-,f

HunranInterfàceUseasGùide

COMMAND PARSING

quotingcharacters

Two single-quote(') or double-quote(,,)charact€rsremovethe
semanticsofspecialcharactersthey surround(but you must use
the samecharacterfor both lhe beginningand endingquote). If a
commandline containsquotedcharacters,the Human Interface
systemcallsthat invoke the commandand parsethe conìmandlin€
do not perform any specialfunctionsassociated
with the
surroundedcharacters,For example,an ampersandsurroundedby
doublequotesis interpretedas a singleampersandand not a
continuationcharacter.
The quotesremovethe semanticsofcharactersthat are specialto
the Human Interfacebut not specialto other layersof the
OperatingSystem.Therefore,quotesdo not removethe semantiqs
ofcharacterssuchas :, /, and /, which are specialto the l/O
System.
To includethe quotingcharacterin the quoted strin& the operator
must specilythe charactertwice or use the other quotingcharacter.
For example:
Ican'l'

rcan'tn

causes:
to be read in the commandÌine.

3.3 PABSING
THECOMMAND
LINE
Whena HumanInterfacecommand
beginsexecuting,
a parsingbufferassociated
with the
command
containsall theparameters
thattheoperatorenteredwheninvokingthe
command(everything
exceptthecommand-name
portionof the invocation
line). The
HumanInterfacemaintainsa pointerfor thisparsingbufferwhichinitiallypointsto the
firstparameter.By invokinganyof thefollowingHumanInterfacesystemcalls,the
command
canreadtheparameters
from theparsingbuffer:
C$BACKUP$CIìAR
C$GET$INPUT$PATHNAME
C$GET$OUTPUT$PATI]NAME
C$GET$PARAMETER
CSGET$CHAR
The systemcallsC$GET$INPUT$PATHNAME,
C$GET$OUTPUT$PATHNAME,
and
C$CET$PARAMETER
readan entireparameter
andcausethe HumanInterfaceto
movethe pointerto the nextparameter.Thesesystemcallsunderstand
quoting
characters,
removethe specialmeaningfrom quotedcharacters,
anddiscardthe quote
characters.

HumanInterfaceUseÌ'sGuide

COMTtrAND
PARSING

The systemcalls,C$BACKUP$CHAR and C$GET$CHAR,seethe parsingbuffer as a
stringof characters.They do not understandthe notion ofquotìng characters;therefore
they do not removethe specialmeaningfrom quotedcharacters,nor do they skip over the
quotcs. C$BACKUP$CllAR causcathc Human Intcrfaccto movc thc pointcr onc
positionbackwards.C$GET$CrIAR readsa singlecharacterand causesthe Human
Interfaceto movethe pointer to the nextcharacter.Exceptfor positioningthe parsing
pointer to a particularplacein the buffer,C$GET$CIIAR shouldnot be usedwith
C$GET$INPUT$PATHNAME,C$GET$OUTPUT$PATHNAME,and
C$GET$PARAME'IER.

3.4 PARSING
INPUTAND
PATHNAMES
OUTPUT
Ifyou restrict the invocationlines ofthe commAndsyou wlite to a form that is similar to
the standardformat discussedearlierin this chapter,you can usethe systemcalls
C$GET$INPUT$PATHNAME and C$GET$OUTPUT$PATHNAME to identirythe
input an.l outpìrtpathnamesin the crmmand line. Becausethe commandline can contain
multiple pathnames,you might needto invokethesesystemcallsseveraltimes to obtain
all the pathnames.
The first call to C$GET$INPUT$PATHNAME readsrhe enrire inparhlist (rhe list of
pathnamesseparatedby commas)into a bìit1èr,movesthe parsingpoìnier to the next
parameter,and retuÍìs the first input pathnameto the command-Likewise,the lirst call
ro C$GET$OUTPUT$PATHNAME notesthe preposition(TO, OVER, or AFTER),
readsthe entire outpath-listinto a buffer, movesthe parsingpointer to the parameter
atter the outpathlist, and returnsthe first output pathnamcto the command. Succeeding
C$GET$INPUT$PATHNAME and C$GET$OUTPUT$PAIINAME callsrerurn
additionalpathnamesfrom the buffe.screatedpreviously,but they do not move the
parsingpointerto the nextparametef
For example,if the parsingbuffer contains:
A,B TO C,D
the first call to C$GET$INPUT$PATIINAME obrainsborh inpur parhnanres(A and B),
retu.ns the ffustone (A) to the caller,and positionsthe pointer at the prepositionTO.
The firsr call to C$GET$OUTPUT$PATHNAME obrainsboth outpur pathnames(c and
D) and returnsthe first one (C) to the caller. C$GET$OUTPUT$PATHNAME also
identifiesTO as the prepositionand posiîionsthe pointer on it The secondcallsto
C$GET$INPUT$PATHNAME and C$GET$OUTPUT$PATHNAME return B and D
resDectivelv
to the caller.

3-6

HumanInterfaceUser'sCuide

COMMAND PARSING

Thesesystemcallshandlesinglepathnames,listsofpathnames,and pathnamescontaining
wild-cardcharacters.However,becauseof this versatiliryand becauseoutput pathnames
are dependenton input pathnameswhenbofh usewild-cardcharacters,you mÌrstmake
cals to C$GET$INPUT$PATHNAME and C$GET$OUTPUT$PATHNAME in a
particularorder. To usethesesystemca11s
effectively,obeythe followingrules:
1.

Alwayscall C$GET$INPUT$PATHNAME ro obrainrhe input parhnamebefore
callìngC$GET$OUTPUT$P^THNA.MEto obtainthe correspondingoutpìrt
pathname. This is necessary
becausewith wild-cardcharacters,the identity of the
output pathnamedependson the identity of the input pathname. Therefore,
C$GET$OUTPUT$PATHNAME cannotdeterminethe oùtout oathnameuntiÌ
C$CET$INPUT$PATIINAME
determines
rhecorresponding
ìnputparhname.

Alwaysalternateyour callsto C$GET$INPUT$PATHNAME and
C$GET$OUTPUT$PATHNAME. This is necessary
to handlewild card characters
and listsof pathnames.Ifyou invoke two callsto C$GET$INPUT$PATHNAME
without an jnrermediatecall to C$GET$OUTPLIT$PATHNAME,you will not be
able to obtainthe first output pathname.Similarly,if you invoke two callsto
C$GET$OUTPUT$PATHNAME without an intermediatecall to
C$CET$INPUT$PATHNAME, the secondcaÌl returnsinvalìd information

C$GET$INPUI$PA I HNAMB and C$GET$OUTPUT$PATHNAME return the
pathnamesin the form of iRMX lI strings. Each stringis a group of bytesin which the
firsl byte containsthe numberofASCII byresthat follow. For lhesesyslemcalls,rhe
remainingbytesin the st.ing containthe pathname.If C$GET$INPUT$PATHNAME
returnsa zerolength string (that is, the first byte is zero),you know that there are no
more pathnamesto obtain.
After callingC$GET$INPUT$PATHNAME and C$GET$OUTPUT$PATHNAME to
obtain the input file and correspondjngoutput file, you can usethe systemcalls
C$CET$INPUT$CONNECTIONand C$GET$OUTPUT$CONNECTIONro obrain
connectionsto îhosefiles. Chapter4 containsmore informationabout
C$GET$INPUT$CONNECTIONand C$GET$OUTPUT$CONNECrIoN. Upon
obtainingconnectionsto the files,you can pertbrn the necessaryl/O operations.
Figure 3-1 containsan exampleof a programthat usesC$CET$INPUT$PATHNAME
and C$GET$OUTPUT$P^THNAME in ìts command-lincparsing(it alsouscs
C$GET$INPUT$CONNECTIONand C$GET$OUTPUT$CONNECTIONto obtain
connectionsto the files). This programis a partial exampleof à COPY comm.nd that
vou could imDlement.

HumanlnterfaceUsefs Guide

CO[fMAND PARSINC

//ar*-***********)t******:r*************
* This exanple demonstrates the use of the follovin8
Huan Incerfacè
* systen calls:
*
*
rq$c$get$ inpuc$pachnaÌne
'f
rq$c$get$outpuÈ$pathname
*
rq$c$cet$ input$connèction
*
rq$c$cet$outputqconnectíon
*
* This prograrì is a possible iúplenentacion of a COPYutility
r.rhose
* purpose 1s to copy daÈa from successive input files to corresponding
* n',rp,,r files
Eor examplè, to cópy filè A tó file B, file C to file
+ D, and file E Èo fite F, an operator could specify the following
* conùnand line:
.
*
,I
C O P YA , C , E T O B , D , F

*
*
*
*
*
*
*
*
*
*
*

+++*+++++++****:,*:!*>t/

copy: D0;
DECI,AREtoken LITERALLY 'SELECTOR';
DECIARE ( inputqpathname , output$pathnane)
STRUCTURE(
length
B\"TE,
char (al)
B Y T E) ,
o\ltputSprep BYTE,
f i rpursto! en. output$token) TOyEN,
excep
i,ùoRD,
exitSexcep I,ùORD;
Sinclude
$include
$include

(/rnx286/inclerror.
1it)
(/rlnx2 B6/inclhi . exr)
(/rnx2 8 6/Ínc/e ios . ext)

/ r L e t r h e f i r s r í n p u p a t h n a m es t r i r g * /
CALL rq$C$get$ input$pathnane (@input$parhnane, s IZE ( inpurgpathnarÌe ) , @excep);
IF excep <> E$OK
THEN
C A L Lr q q e x i t $ i o $ j o b ( e x c e p , N I L , l Q e x i t $ e x c e p ) ;

Figure3-1. C$GETINPUT$PATHNAME
andC$GET$OUTPUT$PATHNAME
Exarnple

3-8

HumanIntedaceUser'sGuide

COMMANDPARSING

D0 l,IHlLE ( input$pathnane . length <> 0);
/* A zero length indícates
morc Ínput paraneters. */
*/
C e t t h e c o r r e s p o n d i n g o u L p u Èp a t h n a m es t r i n g
/*
outputSprep - rq$c$get$output$pathnane (Goutpur$pathnarne,
SlZE(output$pathnane),
! a ( 7 , , T O: C O : ' ) , G e x c e P ) ;
IF excep <> E90K
THEN
CALL rq$exit$io$job
(excep, NlL, laexit$excep) ;
/*

Establish

connection wilh

the pair

of input

and output files

inputStoken - rq$c$get9Ínput$connection (Ginpur9parhnane, Gexcep) ;
IF excep o E$oK
THEN
caLL rqîe!it$ió$job (excep, NIL, @e!ir9excep);
output$loken - rq$c$get$output$connection (@output$pathname,
outputqprep, Gexcep);
lF excep c E$OK
THEN
C A L Lr q $ é x i r $ i o 9 j o b ( e x c e p , N I L , G e x i È g e x c e p ) ;

Codè to copy data and close both fíles

C € L t h e n e x t : n p u L p a t h n a m es r r i n g + /
CALL rqqcSgetS inputqpathnanìe ( Ginputqpathnane ,
r IZE( inputijpathname ), Gexcep) ;
lF excep <> E90K
THEN
C A L Lr q $ e x i t $ i ó $ j o b ( e x c e p , N I L , @ è x i t $ e x . e p ) ;

END /*
/*

Fìnich

D0 h'llllE
Ì/n

nf^.acsino

cALl- rq$exit$iogjob

(cxcep, NIL, Gexitgéxcep);

END copy;
Figure 3-1. C$GET$INPUT$PATHNAME and CSGET$OUTPUT$PATHNAME Example

Human IdterfacelIser's Guide

3-9

COMMAND PARSINC

IN INPUTAND
3.5 WILD.CARD
CHARACTERS
OUTPUT
PATHNAMES
wild-cardcharacters
providea shorthand
notationfor specifying
severalfilesin a single
reference.TheHumanInterfacesupports
twowild'cardchaaacters
for usein the last
compooeot (this ùrearìsthe last parameter, Ilot just the last sharact€r) of irrput or output

pathnames.The wild-cardcharactersare:
The questionmark matchesany singlecharacter.For example,the name
"FILE?" could imply all of the followingnames(and more):

FILEl
FILE2
FILEX
*

The asteriskmatchesany sequenceofcharacters(includingzero
characters).For example,the name"*FTLE"could imply all ofthe
followingfiles (and more):
OBJECTFILE
FILE
V1.2FILE
AFILE

The followingexampleillustratesboth the correctand incorrectusageof a wild-cardas
the last componentin a list ofpathnames. You can enter:
/f'.yLrb/ r i,re*
/Iiylrb/*.obj
Entering
/*r7h/îíLe7
will cause an error. Tl\e Operator'sGuide To Tlrc Ertenrled íRMX II Human Inteface
descfibeshow to ùsewild-cardcharacterswhen enteringcommands.It alsodisc[sscs
restrictionsand operationalcharacteristics
ofwhich an operatorshouldbe aware. Refer
to that manualfor more informationaboutusingwild-cardcharactersin file names.
The C$GET$INPUT$PATHNAME and C$cET$OUTPUT$PATHNAME systemcalls
automaticallyhandlepathnamesthat containìrild-cardcharacters.They treat a \rildcardedpathnameas a list ofpathnames.
C$GET$INPUT$PATHNAME matcheswild cards. That is, eachtime you call it, it
comparesthe wild-cardedcomponentwith the files in the specifieddirectoryand returns
the pathnameof the next file that matches.For example,if an input pathnameisl

3-10

HumanlnterfaceUseasGuide

COMMANDPARSING

: PROG:PLM/A*'

C$GET$INPUT$PATHNAME
searches
the :PROG:PLMdirectoryandreturnsthe
pathnameof thenextfile thatbeginswith theletter"A".
C$GET$OUTPUT$PATHNAME
generates
wild cards.Eachtimeyoucallit, it
compares
thewild-carded
outputpathname
with thewild-carded
inputpathnameandwith
the mostrecentpathname
returnedby CgcET$INPUT$PATI{NAME.
Thenit generates
a coúesponding
outputpathname
basedon thatinformation.The outputpathname
could
referto an odstingfile or to a file thatdoesnot yetexist.As an example,
suppose
an
operator'sdefaultdirectorycontainsthefollowingfiles:
ALPHA
All
ADAM

BETA
811
C1I

Nowsuppose
thatyouhavewrittena command
calledREFINEthatreadssome
informationfrom an inputfile,adjuststhatinformationin somemanner,andwritesthe
informationto an outputfile. Assuming
thatyouinterleaved
thecallsto
C$cET$INPUT$PAr
HNAME andC$GETSOUTPUT$PATHNAME
correcrlywhen
youwrotethecommand,
an operatorcouldentera command
line asfollows:
REFINE A*,8* TO C*, D*

In thiscase,C$GET$INPUT$PATHNAME
andC$GET$OUTPUT$PATI{NAME
returnpathnames
asfollows:
Pathname
lìstreturned
CorrcsponrJing
pathname
list
by C$GET$INPUT$PATHNAME
returnedby
C$GET$OUTPUT$PATHNAME
ALPIIA
A1l
ADAM
BETA
811

CLPHA
c11
CDAM
DETA
D11

Because the file Cl1 aheady exists,the Human lnterface would display the following
messagebefore writing to the file:
Cl1, already exísts,

OVERIÌRITE?

If theoperatoranswers
yesto theprompt,theHumanInterfaceoverwrites
the file.

Hùman Infelace llser's Cuiil€

3.11

COMMANDPARSING

3.6 PARSING
OTHERPARAMETERS
The C$GET$PARAMETER systemcall is îlso availablefor parsingcommandlìnesof the
standardformat. You can usethis systemcall for the followingpurposes:
.

To parseparameterswhich appearafter the input and output pathnames.

To parseall parameters,if the commanddoesnot useinput and output files-

To parsethe input and output pathnames,if the commandrequiresa prepositìon
other than TO, OVER, or AFTER.

Ifyou useC$GET$PARAMEIER to parseinput and output pathnames,you must
provide additionalcodeto handlewild-cardcharactersthat may appearin the command
line. This is unlike C$GEfiINPUfiPATHNAME and
C$GET$OUTPUT$PATHNAME whichhandlewild-cardcharactersautomatically.For
example,supposea commandline containsthe pathname:
FILE*
Ifyou useC$GET$INPUT$PATHNAME to parsethis parameter,the systemc:ll
assumesthat FILE* is a wild'cardedpathname.It searchesthe operator'sdefault
dìrectoryand returnsthe pathnameof the first file whosenamestartswith the characters
"FILE'. Subseqùentcallsto C$GET$INPUT$PATHNAME return other pathnamesthat
meet theseconditìons.
However,iî you use C$GET$PARAMETER to parsethe sameparameter,the systemcall
returnsthe valuel
FILE*
It doesnot know'thatthe charactersreoresenta oathname.nor doesit know that the
asteriskrepresentsa wild card.
When caled, C$GET$PARAMETER parsesa singleparameterand movesthe pointer of
the parsingbuffer to the next parameter.The paramete.returnedas a result of this call
can be in any ofthe followingforms:
value'list

1-tt

A valueor g oup of valucsscparatedby commas.The systemcall
returnsthe entirelist in the form oi a string table (describedin
Appendi{ B). It placeseachof the valuesin the vnluelist in a
separatestring.

HumanlnterfaceUser'sCuide

CONIMANDPARSING

keJword= valuclist A kelword indicatingthe kind ofparameter,followedby a value
or kelword(value- (or group of values,separated
by commas).The presenceofthe
list)
cqual signor the parentheseslersthe sysÌemcall recognize
ke)rwordparameterswithout foreknowledgeof the ke)'!vords.It
alsoinforms the systemcall that the charactersfollowingthe equal
sign(or the charactersin parenthesis)representa value-listand
not a separateparameter. The systemcall returnsthe key,"vord
in a
stringand the valuelist in a string table.
kelword valuelist

A kelword indicatingthe kind ofparameter,followedby a value
(or group ofvalues,separatedby commas).In this case,sincethe
kervord and valuelist are separatedby spacesinsteadofby an
equalsignor parentheses,
the kefvord is referred to as a
preposition.In order for the systemcall to recognizethat this
stÍuctureis a ketrrord/value-listinsteadof two separate
p rarn€l€rs,you must supply,as input to th€ systemcallra string
tablecontainingall the possibleplepositionsthet coùld occur. The
systemcalJchecksthis ]jst to determinewhethera group of
charactersseparatedby spacesis a prepositionkeylvordor a
separate
parameter

Individualparameters
areseparated
by spaces.
In general,thevaluelistof a parameter
is eithera singlevalueor a lisl ofvaluesseparated
bycommas.C$GET$PARAMETER
returnseachof thesevaluesasa stringin a string
table.However,an individualvaluecanitselfconsistofa vaÌue-list.Ifa groupofvalues
(separat€dby €omnìàs);s encìosedùÌ parenlhescs,
C$cET$PARAMETER lrcars thc
valuesas a singlevalue,returningthem in a singlestring. For example,in the following
value-list:
A,(B,C,D),E
C$GET$PARAMETER considers"B,C,D"as a singlevalue. Therefore,thevaluelist
consistsof three vîlues: "A", "B,C,D",and "E".
Figure3-2 containsan exampleof a programthat usesC$GET$PARAMETER in its
command-lineparsing.

HumanInterfaceUser'sGuide

3-13

CONIMANDPARSING

**********************
/*********************************
* This è).anple demonstrates the use of the following Huan lnlerface
* systen call:
)
r
*

*
*
:f
*
*
*

rdqaqoÀrqn,

*
*

rrÒaiar

*
This progran nakcs ucc of rq$c$gct$paranctcr to parsc a kclrord
paranèter in a corùnand1ine.
Here, the kelvord, "SIZE", is parsed
and its valuè portíon converted to a word walue and placed in
For exaÍrple, an oper:ator: could specify the follo\ríng
"size$vat".
connnand line:

*
*
*

PROG1 SIZE : 4OO

*
*

\nrp

a default

îh,r

i\p

'icl7_i

lec€íves

value *******x*****)r*****x**/

progl:

DO;

DECIAREtoken LITERALLY 'SELECTOR'
;
9i.cr1idé (/rmx286/inclerror lit)
ext)
$ ínclude (/rnx286linclhi.
(/rnx286lincleios
. ext)
9include
(len BYTE,
LITERALLY 'STRUCTURE
str (r) BYTE) ,
STRING9TABLE
LITERALLY'STRUCTURE
(m],'n$entries BYTE,
entries (l) BYTE)',
PAtA}tETER$KE1'1JORD$f.fr!(L I T E R A L L Y' 2 0 ' ,
VALUE9TABLE$M,A,I
L I T E R A L L Y' 8 0 ' ,
DEFAULT$SIZE
LITERALLY ' 1OO';

DECIIRE STRTNC

DECIjRE vaÌue$rableSbuf

(VALUE$TABLE$}IdT)BYTE,

Receives string

table

valuegtable
STRING$TABLE
AT (Gwalue$rable$buf),
value$srr$ptr
POINTER,
vaÌue$scr BASEDvalue$scr$ptr STRING; /* For refer.encing strrngs
in the st ring rable */
DECIAREparaneter$keyrord$buf

( PARAMETLRSKUYI,/ORD$l{AX)
BYTE, /* Receives
the ke)ryord
strina */
parameterSke).word STRINCAT (Gparaneter$kelvord$buf),
excep WORD
,
noreSparam UoRD,
(size$wal, i) l.IoRD;

Figùre3-2. C$GET$PARANÍ
ETER Example

3-I,f

HumanInterfaceUser'sCuide

CONfilfAND PARSING

/* GeE the next paralìeter, if present */
nìoIe$param = rqSc$eet$paranìètei ( GparaneterSkeFord,

PARAMETERSKE\uoRDgMÀ{,

Gvatueqrable, VALUEgTABLEgMAX,
N l L , N I L , @ e x c e )p;
IF (excep = E9oK) AND (nore$paran) THEN
- ,S,) AND ,/* rs rhe kqvord, 'SrzD,? .r/
IF (paranèrer$kè)vord.srr(0)
(paramerer$ke).\,rord.str ( 1) = ,r,) THEN
DO;
v a l u e $ s t r $ p t r : @ v a f u e $ t a b l e e. n t r í e s ; / * P o i n r r o t s r e n c r y i n
rable */
size$va1 - 0;
- 1; ,/* Convert nurTber string to word
DO i - 0 to value$str.len
vdlue +/
sizFgval - sizpSval * ì0;
- 30H);
size$val - size$va1 + (valuegstr.srr(i)
END;
END;
EI-SE
,SIZE, parameter is nor presen!,
size9val - DEFAULT$SIZE
/ *;I f r h e
use rhe default size. */

conrinue ùiÈh rhe r:esr of the progran

Finish I/0 processins ,f/
/*
C A L Lr q g è x i t g i o $ j o b ( e x c e p , N I L , @ e x i r g e x c e p ) ;
E N Dp r o g l ;

FigureJ-2. C$GET$PARNÍETERExample

3.7 PARSING
NONSTANDARD
COMMAND
LINES
If the commandline you write followsthe recommendedstructuredescribedeàrlier in this
chapter,you can useC$GET$INPUT$PATHNAME,C$GET$OUTPUT$PATHNAME,
anclC$GET$PARAMETER to parselhe commandline. However,ifyou requirc irn
invocationline of a different form, you might not be able to usethesesystemcalls- The
followingsectionsdiscusstwo q4)€sof nonsrandartlcommandlines:one that is similar to
the standardand one that is completelydilferent.

Human Inteface Uset's Guide

J-15

COMNIA.ND PA.RSINC

3.7.1Variations
OnTheStandardCommandLine
The "Standard
Command-Line
Structure"
sectionof thischapterrecommends
thatthe
firstparametels
ofyour conìnìarìds
be a list of ilput patlìtalnes,a pleposition,aDda list
of outputpathnames.
With thisconvention,
commands
alwayscail
C$GET$INPUT$PATHNAME
andC$GET$OUTPUT$PATHNAME
first,before
obtaininganyoptionalparameters.
Therefore,the inputandoutputpathnames
arethe
onlyposition-dependent
prrametersin yourcommands;
otherparrmeterscan,ìlfear in
any order and can be optional.
However,supposeyou want to structureyour commandsso that other parametersappear
before the input and output pathnames.You can stìlluse C$GET$INPUT$PATHNAME
and C$GE'l$OUI PU I $PAl HNAME to parsethe inputand outputpathnames.But,you
haveto ensurethat your commandknowswhich of the parameterscontainthe input and
output pathnames.You calrdo this in severalways. Two of them are:
.

Enforce a rigid structureon the commandline. For example,supposeyou want two
parametersto appearbefore the input and outpul pathnames,suchasl
command p1 p2 input-pathnameprep output-pathname
Your commandcould useC$GET$PARAMETER to parsethe first and second
parameters.Then it could use C$GET$TNPUT$PTHNAME and
C$GET$OUTPUT$PATHNAME to parsethe input and outpìrtpathnames.If you
do this,p1 and p2 are position-clependent
parameterswhich must be ìncluded
wheneverthe commandis invoked.

Us€ a separateparameteras a switchto infornr the corùrnandthat th€ parallretErsthat
follow are input and output pathnames.This methodrequiresmore code to
implementbut it cen a[ow you to mrke all your p.ìrameters(includingthe input and
outpuî pathnames)position-independent.
For example,you could implementyour commandsuchthat wheneverthe operator
entereda parametercalledFROM, it \"-ouldsignalthe commandthat the next
paramctcrswcrc input and output pathnames.This commandcould containa main
loop that usedC$GET$PARAMETER to parseparameters.Wheneverthe command
receiveda parumeterwhosevaluewas"FROM", it couldcall anotherportion ofcode
that usedC$GET$INPUT$PATHNAME and C$cBT$OUTPUfi PATIINAME.
After retrievingthe input and output pathnames,!he codecould return to the main
loop to continueprocessingparameters.
A hypotheticalcommandof this sort might be calÌedRITRI[Vtr, a commandthat
retrievesjnformationfrom variousdata bases.The operaiorcould invokethis
commandwith a commantlline suchas:
RETRIEVE NAMEs ADDRESSESPHoNES FRoM file I TO file2
In this command,operatorscan speciryv/hat thevwant to retrievebeforethey speciry
where to get the information.

Human Inteface User'sCuide

COMMANDPARSING

3.7.2 OtherNonstandardCommandLines
In sorrreinstances,you might want your commandline to look completelydifferent from
that describedearlier in this chapter. For example,supposeyou require a syntaxin which
the followingrulcs apply:
.

Spaceshaveno significanceand canbe omitted betweenparameters.

A prefix charactermust be before eachparameter(a "g" indicatesan input file, an ,,@,,
indìcatesan output file, and a ',-"indicaîesall other parameters).

With this kind ofsyntax,a usercould invokea command(in this examplethe commandis
calledREFINE) as follows:
REFINT $infile-mediumt11
oulfile
where infile is the file from which to read informarion.outfile is the file in which REFINE
shouldplaceits outpuî, and mediumis a parameterthat further directsthe processing.
lfyou require the syntaxoutlinedin this example(or any other nonstandardsyntax),you
cannotuseC$GET$INPUT$PATHNAME,C$cET$OUTPUT$PATHNAME, and
C$GET$PARAMETER to parsethe individualparamerers.Any of thesesystemcalls
would return the entire parameterlist as a singleparameter.
For casessuchas this,you can usethe CgBACKUP$CtlAR and the C$CET$CHAR
systemcallsto parsethe commandline. Thesesysremcallsperform a singlc,simplc
operation. C$BACKUP$CHAR movesthe positionpointer backwardsone position.
C$GET$CHAR returnsa sìngìecharacterfrom the commandline and movesthe pointer
to the next chiracîer. Thesesystemcatlsdo not understandthe notion ofparametersns
erplainedearlier in this chapter. Nor do they understandwild-cardcharactersor quoting
chaaacters.
C$BACKUP$C[L{R and C$cET$CHAR requireyou to provide the parsingalgorÌthmin
your own proglam, becaùsethey make no assumptionsaboutthe structureor order of
parameters.However,by usingthesesystemcalls,you can enforceany commandsyntax
you choose.
BecauseC$BACKUP$Cr{AR and C$GET$CFIARmove the pointer characrerby
character,not parameterby parameter,yorì shouldtake carewhen usingthem in the same
programwith C$GET$INPUT$PATHNAME,C$CET$OUTPUT$PATHNAME, and
C$GET$PARAMETER. You must ensurethat C$BACKUP$CILARand
C$GET$CHAR ìeavethe pointer pointìngat the beginningof a parameter(or at blank
characterswhich immediatelyprecedethe parameter)before invokingflny olrhe other
systemcaÌls.

Human InterfaceUser's Cuide

COMMAND PARSING

TOANOTHER
PARSING
BUFFER
3.8 SWITCHING
When a commandbeginsexecution,it hasa parsingbuffer that is set up by the Human
Interfaceto containthe parametersof the command. The commandparsingsystemcalls
listed in this chapteroperateon that parsingbuffer. This allowsthe commandto parseits
parameters.
Somecommandsmight require the ability to parseadditionallines of text (for example,
an editor needsto parseindividualeditor commands)after the originalcommand
invocation.A commandsuchas this cannotusethe Human Interface-providedparsing
bìrfferbecauseit has no way ofplacing informationin the buffer, and becausert cannot
resetthe parsingpointer to the beginningof the buffer.
To meet the needsofcommandssuchas this, the Human Interfaceprovidesa systemcall
to changeîhe parsingbuffer from the one the Human Interfaceprovidesto one that the
commandprovides. This systemcall,C$SET$PARSE$BUFFER,
switchesthe parsing
buffcr ànd s€lsth€ parsìngpointer to the b€ginningof the bufter.
One of the parametersof the C$SET$PARSE$BUFFERsystemcall (buff$p) is a pointer
to a buffer containingthe text to be parsed. This buffer can containtext read from the
terminal,text read from a file. or eventext that you "hard code"into the command. After
the call to C$SET$PARSE$BUFFER,
the followingcommandparsingsystemcallsobtain
informationfrom the new prrsing buffer:
C$GET$PARAMETER
C$GEÎ$CI'IAR
C$BACKUPSCI{AR
The other commandparsingcalls(C$GET$INPUT$PATHNAME and
C$GET$OUTPUT$PATHNAME) are not affectedby callsto
C$SET$PARSE$BUFFER.Thesecallsalwaysobtainpathnamesîrom the original
parsingbuffer (the commandline).
When you establisha newparsingbuffer,C$SET$PARSE$BUFFERsetsthe parsing
pointer to the beginningof the butler. This alkrwsyou to useone bufler tbr parsingmany
lines of text. For example,supposeyour commandhas severalsub-commands.Each time
the operatorentersa sub-command,
your commandreadsthe sub,commandinro a buffer,
cals C$SET$PARSE$BUFFERto resetthe parsingpointer,and parsesthe subcommand. The programflow for an operationljke thjs couldbe:
1.

Read the informationfrom the terminal into a buffer (use
C$SENDIiCOtrjRESPONSE,
C$SEND$EO$RESPONSE,
or an Extendedl/O
Systemcall).

Call C$SET$PARSE$BUFFERto set the parsingbuflèr to the buffer contàr'ning
the sub-command.This setsthe parsingpojnter to rhe beginningof the buffer.

3-18

HumanInterfaceUsey'sCuide

COMMANDPARSING

Parsethe sub-conmaodusiogCSGETSPARAMETER,C$BACKUP$CHAR or
C$GET$CHAR systemcalls.

Perform the operationsrequestedby the sub-command.

Go backto step 1. Continuethis loop until the operatorex;tsfrom the command.

Ifyou speciff ML or a zero valuefor the bufflp parameterof C$SET$PARSE$BUFFER,
the parsingbuffer s\ritchesbackto the originalcommandline buffer. However,the
parsingpointer doesnot resetto the beginnìngof the buffer; it remainspointing at the
next paramete.in the commandline. lhis allowsyou, if you wish,to parsepart of the
commandline, switchbuffersand parsea portion of anotherbuffer, and switchbackîo
the comnìandline.
There is one problemwith switchingbackand forth betweenparsingbuffcrs. Excepr
whenyou switchto the commandline buifer, everytime you call
C$SET$PARSE$BUFFER,
the parsingpointer movesto the srart of rhe buffer.
Therefore,you loseyour placein the buffer. However,C$SET$pARSE$BUFFER
returns,in its offsetptìrameter,a valuethat indicatesthe positionof the pointer in the
previousbuffer. This valuespecifiesthe offsetof the pointer,in bytes,from the beginning
of the buffer. Ifyou intend to swiîchbackto that builer (by againcalling
CIiSET$PARSE$BUFFER),
you can usethis valueto move the poinîer to its previous
posrtlon.
One way to do this is to usethe C$GET$CIIAR systemcall to move the parsingpointer
backto its previousposirion. Afrcr switchingbackto the original buffer,calt
C$GET$CHAR the nlrmberof timesspecifiedin the ofl.setparameterof the first
C$SET$PARSE$RIIFFERca[ (not the one rhar s*,itchedbackto the buffer). This
positionsthe pointer to its previouslocation. You can then continueparsìngparameters
ftom th€ pojnt at whichvou left ofi
Another way to do this is by îreatingyour parsingbuffer as an array ofcharacters(an
array caled CHAR, lbr example).When you call C$SET$PARSE$BUFFERrhe first
t;me, you can specifythe buf$p parameterto point to the first elementof the array
(CHAR(o), for example).Then,whenyou switchparsingbutiers,
C$SET$PARSE$BUFFERretu.ns,in the offsetparameter,the numberof bytesalready
parsed. Wlcn you svritchbackto the first parsiogbuffer,you can userhis offsetvalueas
an indexinto the array;that is, havethe buff$pparameterpoinr ro CHAR(offset).

Human hterface Usels Gùide

3.19

COI\fMAND PARSING

3.9 OBTAINING
THECOMMAND
NAME
A user invokesa commandby specilyingthe pathnameofthe file containingits object
codeand any pai aor€t€rs the conìmandrequires. The Hurrun Intcr facEplacesthe
parametersin a parsingbuffer.which the commandcan aocess
by invokingthe system
callsdescribedearlier in this chapter. In addition,the Human Interfaceplîces the
commandnamein anotherbuffer. The commandcan obtainthis nameby calling
C$CEfiCOMMAND$NAME.
C$GE]$COMMAND$NAME doesnot operateon the parsingbùffer usedby the other
commandparsingsyst€mcalls. Nor is jt affectedby the C$SET$PARSE$BUFFER
system.lt can be calledmultiple times;eachtime it returnsthe samecommandname.
Ifthe operatorentersthe completepathnameof the command(includingthe logical
name),thc command-namcbuffcr containsexactlywhat the operatorente.ed. However,
if the operatorentersa commandnamewithout a logicalname,the Human Interface
àutomaticallysearchesa numberof directoriesfor the command. ln thìs case,the
command-name
buffer containsnot onÌy the nam€the operatorentered,but also the
directorycontaining
the conmand(suchas :SYSTEM:,TPROG:.
or :$:).
Therefore,a commandcan usethe valueretumed by C$GET$COMMAND$NAME and
the circumflexpathnameseparator(^) to accessthe directoryin which it resides.For
example,if "command-name"
is the namereceivedfrom C$GET$COMMA^-D$NAME, a
commandcould accessits directoryby usingthe pathname:
conmand,namel

It couldaccess
anotherfile in the dìrertoryby specirying
thepathnamel
comrìand-nane/file

3-20

HumanInterfaceUser'sGuide

4.1 OVERVIEW
The Human Interfaceprovidesseve.alsystemcallsthat establishconnectionsto input and
output files,communicatewith the opeaator'sterminal,and format exceptioncodesinto
messages
that can be sentto the operator. This chapterdiscusses
thesesystemcalls.

4.2 ESTABLISHING
INPUTANDOUTPUT
CONNECTIONS
The Human lnterfaceprovjdestwo systemcallsfor estab[shingconnectionsto input and
output files: C$GET$INPUT$CONNECTIONand CgGETSOUTPUT$CONNECTtON.
Thesesystemcallsare structuredso that you can usethe output from
C$GET$INPUT$PATHNAME and C$GET$OUTPUT$PATHNAME as input to these
systemcalls.

4.2.1 UsingC$GET$INPUT$CONNECTION
C$GET$INPUT$CONNECTIONobtainsa connectionto a iile and oDensthat
connectionfor reading. One of rhe paramerersol C$GET$INPUT$CòNNECIION is a
pointer to a stringcontainingîhe pathnameof the file for which the connectionìs sought.
This pathnamecan be the pathnamereturnedby C$GET$ÌNPUT$PATHNAME or it can
be the pathnameof any other file to whichyou want a connection.If
C$CEfiINPUT$CONNECTION càoDd obraina connecrionro rhe specifiedfile fo. any
reason,iî returnsan exceptioncodeand writes a messageto :CO: (normallythe
operator'sterminal) to indicatethe tlpe ofproblem. For examplc,ifthc spccificdinput
lile doesnot exist,C$GET$INPUT$CONNECIION displaysthe followingmessage:
,file not found
The systemcall displayssimilar messages
in other situations.Refer to the descriptionof
C$GET$INPUT$CONNECTIONin the dxlended|RMX II Human InterfaceSystemCalh
Reference
Manual îot more information.
BecauseC$GET$INPUT$CONNECTIONreturnsmessages
to the operatorin the event
of an exceptionalcondition,your commanddoesnot haveto return addìtionalmessages
unìessyou require them The commandmust decideonly *'hether to abort or to continue
processing.

Human InterfacelJsecscuide

4-l

l/o PRoaEsslN(}

4.2.2 UsingC$GET$OUTPUT$CONNECTION
obtainsa connection
to a file andopensthat
C$GET$OUTPUT$CONNECTION
oneofthe
conncction
for writing.As iD thecaseof C$GET$INPUT$CONNECTION,
parameters
is a pointerto a stringcontaining
the
of C$GET$OUTPUT$CoNNECTIoN
pathname of the file for which a connection is sought. This pathname can be the

pathnamereturnedby C$GET$oUTPUT$PATHNAME or it can be the pathnameof
any other file to whichyou want a connection.There is anotherparameterin
C$GET$OUTPUT$CONNECTIONwhich specifiesthe tlpe of prepositionto usewhen
writing to the output file (TO, OVER, or AFTER). This prepositiongovernshow data
getswritten to the file.
Ifyou specirythe TO prepositionand the pathnameof an existingfìle,
C$GET$OUTPUT$CONNECTIONpromptsthe operatorfor permissionto deletethe
existingfile. This prompt appearsas:
,aheadyexists,
OVERWRITE?
If the operatorenterca "Y" or "y" (for "yes"),the systemcall obtainsthe connectionto the
existingfile. If the operatorentersan "R" or "r" (for "repeàt"),the systemcall also obtains
the connectionto the existingfile, and it givesthe systemcallpermissionto obtain
without promptingfor permissionto delete
additionaloutput connections,if necessary,
existingfiles. If the operatorentersany other character,the systemcall returnsan
exceptioncodewithout obtaininga connectionto the file.
Ifyou specifythe OVER preposition,C$GET$OUTPUT$CONNECTIoN obtaìnsthe
connectionwithout promptingthe operatorfor permission.
Ifyou specif the AFTER preposition,C$GEI$OUTPUT$CONNECTION obtainsthe
connectionwithout promptingthe operatorfor permissìon.lt alsoseeksto the end of file
before returningcontrol. Thus,any informationyou write to the file will not overwritethe
existinginformation. This is unlike TO and OVER whichcause
C$GET$OUTPUT$CONNECTIONto leavethe file pointer at the beginningof the file.
If tlìe operatordo€snot haveth€ prop€r rcccssrights 1()thc lilc, or if for somereason
C$GET$OUTPUT$CONNECTIONcannotobtaina connectionto the file.
C$GET$OUTPUT$CONNECTIONreturnsan exceptjoncodeand displaysa messageat
the operator'sterminal. Refer to the descriptionof C$cET$OUTPUT$CONNECIION
1nthe Ertenrled iRùlX I Human Inteiarc S\,ttemCalls ReferenceManual for more
information.

4.2.3 ExampleProgramScenario
A normalscenario
for usingC$GET$INPUT$CONNECTION
and
C$GET$OUTPUT$CONNECTION
is asfollowsl

1-2

Human InterfaceUser'sGuide

l/o PRocEssrNG

DO WHILE mo.einputandoutputfiles
Obtaininputpathnanrc
from command
linewirhC$GET$INPUT$PATHNAME
Obtainoutputpathname
f.om command
linewith
C$GET$OUTPUT$PATHNAME
Obtainconnection
to irput file with C$GET$INPUT$CONNECTION
Obtain conne.tion to output file with

C$GET$OUTPUT$CONNECTTON
Readinformationfrom hput file
Perfoamcommandoperations
on infomation
Writeinformationto outputfile
Deleteconnections
to inputandoutputfiles
END
The programlistingin Figure3-1showsa partialimplementatìon
of thisscenario.

4.3 COMMUNICATING
WITHTHEOPERATOR'S
TERMINAL
The Human Interfaceprovidestwo systemcallsthat easethe processof communicating
with the operator'sterminal. They are C$SEND$CO$RESPONSE
and
C$SEND$EO$RESPONSE.Each of thesesystemcallscombinesinto a singlesystemcall
severaloperationsthat you would normallyperform when communicatingwith the
terminal.
In its generalform, C$SEND$CO$RESPONSE
establishes
connectionsto :CI: (console
input) and :CO: (consoleoutput),writesa messageto :CO:,and readsa messagefrom
:CI:. As input to this systemcall,you can specilythe messageto be sent,the sizeof the
messageto be received,and the buffer to receivethe message.Dependingon the values
you choosefor the parameters,you can erther:
o

Senda messageand receivea message

\Àithoutwaitinglo receivea me\\age
Senda message

Receivea messagewithout sendinga message

lfyou useC$SEND$CO$RESPONSE,
you do not haveto invokeother systemcallsto
attach,open,read from. or write to the operator'stermìnal.

Human Inte ace User,s Cuide

4-3

I/O PROCESSTNG

There is a differencebemeenC$SEND$CO$RESPONSE
and
C$SEND$EO$RESPONSE.C$SEND$CO$RESPONSE
dealsspecificallywith the
logicalnames:CI: and :CO:. Therefore,its input and output can be redirectedto files by
'lhis
changingthe pathnamesrepresentedby theselogicalnames.
is what happenswhen
an operatorplacesa commandin a SUBMIT file; SUBMIT assumesthat :CI: is the
SUBMIT tile and lhal :CO; is the outDutfile sDeliliedin the SUBMIT command. On the
other hand,while C$SEND$EO$RESPONSE
performsthe sameoperationsas
C$SEND$CO$RESPONSE,
C$SEND$EO$RESPONSEalwaysreadsinformation from
and writes informationto the operator'sterminal. Input and output cannotbe tedirected
with C$SEND$EO$RESPONSE.
C$SEND$EO$RESPONSE
is especiallyusefulifyou havemultiple taskscommunicating
with a singleterminal- If a task useseither of thesesystemcallsand requestsa response
from the terminal,no other output is displayedat the terminaluntil the operatorentersa
responseto the first systemcall. Atier the operator.esponds,taskscan sendfurther
informationto the terminal. This mechanism,when usedby all the taskswhicb
communicatewith the terminal,preventsthe operatorfrom receivingseveralrequestsfor
inîormationbefore beingableto respondto the first one.

4.4 FORMATTING
MESSAGES
BASEDON EXCEPTION
CODES
Wlenever you includeiRMX U systemcallsin the codeof a commandthat you write, it is
possiblefor thosesystemcallsto encounterexceptionalconditions.Exceptional
conditionsare dividedinto two categories:programmingerrors and environrnental
conditions.Programmingerrors occurwhen the iRMX II OperatingSystemdetectsa
conditionthat normallycanbe avoidedby correctcoding. Environmentalconditions,in
contrast,are generallyoutsidethe corìtrolof thc applicaljonprogram.
Even the most thoroughìydehrrgged
commandscan encounterexceptionalconditions.
The exceptionaÌconditionscan arjsefiom invalid operatorentries,lack of secondary
storagespace,media errors,and other problemsoverwhich the commandhasno conîrol.
The Human lnteriaceprovidesa defaultexceptionhandlerto handleexceptional
conditionsin commandsthat you write. This exceptionhandlerreceivescontrol on the
occurrenceof all exceptionalconditions.It displaysthe exceptioncodevalueand
mnemonicat the operator'stermìnaland abortsthe command.
ln many cases,you might want to provideyour own cxccprionhandling,either ro pass
additionalinformationto the operatoror to allow the operatoranotherchanceto enter
correct informrtion In sùchcases,you can rse the Nucleussystemcalls
GET$EXCEPTiON$HANDLER and SET$EXCEPTION$HAN'DLERto assrgnyour
own exceptionhandleror to cancelthe effectof the defaultexceptionhandleron someor
ail exceptionsthat occur il your command. Relet to fhe ExîendedikMX II Nucleus Sjstem
Calb Refercnce
Manual for more informationaboutthesesystemcalls.

4-4

Human Intedace User'sGuide

I/O PROCESSING

When you pcrform your own exceptionhandling,you will probablycreatespecial
messages
that you return to the operatorin the eventof certainexceptionalconditions.
However,you might not want to createmessages
for all possiblccxccptioncodes.For this
situatior! the Human Interfaceprovidesthe C$FORMAT$EXCEPTION systemcall.
C$FORMAT$EXCEPTION acceptsan exceptioncodevalue as input and returnsa string
whosecontentsdescribethe exceptionalcondition. You can usethis strhg as input to a
systemcall suchas C$SEND$CO$RESPONSE
to write ihe informationro rhe opetator's
terminal. By usingC$FORMAT$EXCEPTIO\ you can rerurn a messagero rhe
operatorfo. all exceptionalconditions,but you do not haveto enlargeyour programby
includingthe text ofthese messages
in the codeofyour command.
The text portion of the stringproducedby CgFORMAT$EXCEPTION consistsof the
exceptioncodevalueand mnemonicin the follo,ringformat:
value : mnemonic
You can displaythis string as is, or you can placeadditionalexplanarorytext in the string
betoredisplayingit. The followingexampleshowsyou how to use
C$FORMAT$EXCEPTION. Supposeyou havea procedurenamedDONOTHING that
waitesan eÍor messageto the screenwheneverthis ptocedureencountersan exception,
You can declarea messageas follows:
DECIéRE
errorSnsg
faired(*)
excep
tocalSèxcep

STRUCTURE(
length
char(80)
BYTE),
B Y T ED A T A ( 3 l , ' D O N O T H I N
pG
rocedure falred x)rx ,),
WORD,
WORD;

Now, whenever an exception is encountered during execution, you can caìl
C$FORMAT$EXCEPTION, as shown helow, to create the default messagefbr the
exception contained in the excepvariable and concatenate it to th€ faiìed messageyou
declared in the variable faled:
caLL MovB(GfaiLèd, @error$nss, fsiled(0)

);

C A L L r q q c $ f o r n a t S e x c e p t i o n ( G e r r o r S m s g ,s I Z E ( e r r o r g n s s ) , e x c e p , 1 ,
G1oca1$èxcèp)i
You can w.ite the error$msg string to the screen. For example, if the excep variable

contains05H,thestringcontainedin error$msg
wouìdbe
' DONOTHINC
procedure falled

:t*:r 0005: ESCoNTEXT,

Refer to the Z:rt€nded íLùlX II Hunatr Intedace Ststem Calls Rderence Mamnl
information about C$FORMAT$EXCEPTION.

HumanlnterfaceUser'sCuide

fot 'l:lorc

4-5

5.1 oVERVIEW
When you write your own command,you migh! want to perform an operationthat is
alreadyprovidedin anothercommand(suchascopyingone file to another,displayinga
directory,€tc.)- Insteadof duplicatingthc codc for this opcrationin your command,you
can invokeHuman Intedacesystemcallsto issuethe commandsthemselves.The effect
of makingthesesystemcallsis the sameas that producedby an operatorenteringa
Human Interfacecommandat the terminal. The Human lnterfaceprovidesthree system
callsto facilitatethis processofprogrammaticcommandinvocation:
C$CREATE$COMMAND$CONNECTION,C$SEND$COMMAND, and
C$DELETE$COMMAND$CONNECTION.
Invokingcommandsprogrammaticallyinvolvesthe followingoperationsl
.

Creatingan object(calleda commandconnection)to storethe commandinvocation
lines

Sendingthe commandline to the commandconnectionand invokingthe command

Deletingthe commandconnection

This chapterdiscusses
theseoperationsand providcsan cxamplcof how thc Extcndcd
iRMX Il systemcallsappearin a program.

5.2 CBEATING
A COMMAND
CONNECTION
Beforeyou can senda commandline to the OperatingSystemto be invoked,you must
createan object (calleda commandconnection)to store the commandline. The
C$CREATE$COMMAND$CONNECTION systemcall createsthis objectand returnsa
îoken for the coîúrand connection.The tokencan be usedin callsto
C$SEND$COMMAND (to sendcommandlinesto the object)and in callsto
C$DELETE$COMN4,A.ND$CONNECTION
(to deÌetethe objectafter usingit).
When you call C$CREATE$COMMAND$CONNECTION.you alsospecifytokensfor
the connectionsthat serveas commandinput and commandoutput for the invoked
comùand. This allowsyou to redirectinput and output for the invokedcommandto
secondarystoragefiles. Or you can speliIy the normal :CI: and :CO:.

Human lnterfaceUset's Guide

5-1

COMMANDPROCESSING

Thecommand
connection
is necessary
to supporttheprocessing
ol multiple-line
commands
withoutinîerference
from othertasks.If not for thecommandconnections.
the OperatingSystemwouldbe unableto determine
whichcontituationlinewentwith
which command when many tasks ìver€ sending command lines to be processed. Th€

providesa placeto storecommand
command
connection
linesuntil the commandis
comDlete.

5.3 SENDING
COMMAND
LINESTOTHECOMMAND
CONNECTION
ANDINVOKING
THECOMMAND
The C$SEND$COMMAND systemcall sendscommandlines to a commandconnection
and,when the commandinv(rcationis complete,invokesthe command. One of the
parametersofthis systemcall is the token for a commandconnection,which identifiesthe
commandconnectionto us€. Anothef pafafirct€ris a pointer to a stringwhich must
containa commandline. The fo.mat of the commandline is the sameas the format for
enteringth€ commandline at a terminal. The commandcan be any iRMX II Human
Interface command (as described in the Operator'sGuide To The Extended iRl\,ÍX II
Human Interface)or anycommandthat you write. However,it can not be a CLI
command.and it cannotusethe aliasfeatureofthe CLl.
If the string speciliedas a parameterto C$SEND$COMMAND containsa complete
commandinvocation,C$SEND$COMLtrANDplacesthe commandline in the command
connectionand invokesthe command.
However,ifthe string docanot containthe entire commandinvocation(that is, it contairs
the "&" as a continuationcharacter),C$SEND$COMMAND placesthe commandline in
the commaddconnectionwithout invokingthe command. [t alsoreturnsan exception
code,E$CONTINUED, to infotm the callingprogramthat the commandis continued.
Additional C$SEND$COMMAND callsplacecontinuaîionIinesin rhe command
connection,combiningthem with the commandlines alreadythere. When
C$SEND$COMMAND sendsthe last portion of the commandhvocation (a line without
a continuationcharacter),it invokesthe entire command.
Onceyou call C$SEND$COMMAND enoughtimes to placea completecommand
invocationin the commandconnection,C$SEND$COMMAND invokesthe command.
This involvesloadingthe contmaodfrorn s€condarystorageand srarfitg iÍ running. The
C$SEND$COMMAND call that irìvokesthe commanddoesnor return control until the
invokedcommandfinishesprocessing.Oncc thc commandfinishesproccssing,you can
usethe commandconnectionfor invokingother commands.

5-2

Human Inteface User's Guide

COMMAND PROCESSING

Thc C$SEND$COMMAND systemcall containstwo pointersto words that rcceive
iRMX II conditioncodes. One of tlÌese(calledexcept$ptrin the systemcall description)
points to a word that receivesthe statusof the C$SEND$COMMAND systemcall. An
E$OK indicatesthat C$SEND$COMMAND re.eivedthe iullcommand invocationand
invokedthe command. An E$CONTINI IED indicatesthat the commanclinvocationis
not complete(the last Linecontaineda continuationcharacter).Other exceptioncodes
indicateother problemswith the systemcall.
The other poirter (calledcommand$except$ptr
in the systemcall description)points to a
wo.d that receivesthe statusof the invokedcommand. This allowsvou to determinethe
statusof the invokedcommand.

5.4 PRIORITY
CONSIDERATIONS
Every commandhasa priority (usuallybasedon the priority of the userwho invokedthe
command)that determineswhen the commandwill be ableto run in relation to the other
tasksin the system.When commandsare invokedvia commandconnections,their
priorities are lowered(numericallyincreased)by one- This ensuresthat the callingtask
(the one that createdthe commandconnection)retainscontrol oveathe commandslt

As a result,a commandinvokeddiectly at the terninal will havea higherpLiority(and
possìblycompletesooner)than the samecommandinvokedvia a commandconnectton.

5.5 DELETING
THECOMMAND
CONNECTION
you shoulddeletethe
After you havefinishedinvokingcommandsprogrammatically,
commandconnection.The C$DELEIE$COMMAND$CONNECTION systemcall
performsthis operation. You do not needto deletethe commandconnectionafter each
commandinvocation,becauselhe commandconnectionis .eusable.However,you should
deletethe commandconnectionafter pedorming all C$SEND$COMNLANDoperations.
This freesthe memoryusedby the datastructuresof the commandconnection.

5.6 EXAMPLE
Figure5-1containsan exampleof a programthatusesl
C$CREATE$COMMAND$CONNECTION
C$SEND$COMMAND
C$DELETE$COMMANDSCONNECTION
Tt invokesthe Human TnterfaceCOPY commaîd Drocrammaticaììv.

Human Intedace User's Guide

COMMAND PROCESSINC

/***********************************************************************
*

This exanple denonstrates

*
*
*

rq$cQcreategconùnand$connection
rqScSsen.l$.onm.nd
rq$cqdeleteSconnand$connection

*
*
*

ThÍs progran uses the previous systen cal1s to invoke rhe conmand
CoPY :F1:OLD to : F1:NEl,ùand then continues normal processing.
Thè prosran is inwoked vith thc comand líne:

*
*

the use

oT lhp

f.llówino

H"r,n

lnl'èrf..p

PROG2

*-*********************+**********:t*:9*:!*:t*********)k***:t*:!*:!**************/

prog2: DO;
DECLAREtoken LITER-ALLY ' SELECTOR';
$include
9include
9include

(/rILy286linclerror. 1it)
(/rìÌx286/inclri.
exr)
(/rnx286lincleios
. ext)

DECLARE(ci$token, co$token, comrìandgconnecriongroken) T0KEN,
(excep, comexcep, e: E90K

THEN

C A L Lr q $ e x i t S i o S j o b ( e x c e p , N l L , @ e x e x c e p ) ;

Figùre 5-1. CommandConnectionExample(continued)

5-4

Human InterfaceUsels Gùide

COMMAND PROCESSINC

/* areaxe comaDd co oecLion */
connandqconnection$token - Èq$c9crearegcomandgconnecrion (ci9roken,
có$tokèn,0,
Gexcep);
IF excep o E9OK
THEN
C A L Lr q $ e x i t $ r o $ j o b ( e x c e p , N I L , Q e x e x c e p ) ;
/* Send.ómn,nd to copy fi1ès */
CALL rqgC$sendqconnand (conùnandgconnecriongroken,
' C O P Y: F l : O L DT O ì F l : N E I I ' ) ,
G (2 3 ,
Gconexcep, @excep);
IF excep <> E$oK
THEN
C A L Lr q $ . x i t $ i o 9 j o b ( e x c e p , N l L , G e x e x c e p ) ;
/* Delete connnandconnection )t/
CALL rqQcSdelete9conlnand$connection ( comand$ connecI iong roken, @excep);
lF excèp o E$OK
THEN
cALl, !rl$exiLSio$j ob (excep, NlL, r4exexcep):
.

n""a of program

/* Finísh I/0 processins */
cÀLL rq$exitSio$job (er.cep, NIL, Gexexcep);
E N Dp r o g 2 :

Figùre 5-1. CommandConnectionExample

Humen Interfece Userrs Guide

6.1oVERV|EW
Normally,when a Human Interfacecommandis executingan operatorcannot
communicatewith the command(or with the applicationsystemin general)unlessthe
commandinitiatesthe communicationby requestinginpùt from the termìnal. This can
presentproblemsif an operatorinadvertentlyentersthe wrongcommand,or if the
operatoadecideswhile the commandis executingthat the commandis unnecessary.
Under thesecìrcumstances,
there are a numberofways the operatorcan abort command
execution.
.

lfthe commandis executinginteractively,the operatorcan enter a Control-C
characterto abort a command.

lfthe commandis runningin the backgroundenvironment(exptainedin Chapter2),
the operatorcan enter the CLI commandsJOBSand KILL to abort a job.

This chapterexplainshow to overridethe defaultControl-C mechaîìsmby providingyour
own codeto processa Control-Ccharacter.For more informationon aborting
backgroundjobs, see the Operator'sGuide To The Ertended íRMX II Human Interlace.

6.2 HOWTHEDEFAULT
CONTROL-C
MECHANISM
WORKS
When the operatorentersa Control-C,the OperatingSystemsendsa unit to a
semaphore.In the defaultcase,it sendsthe unit to a semaphoreestablishedby the
Human Interface. A Human Interfacetaskwaits at that semaphoreto receivethe unit.
When it receivesthe unit, jt abortsthe commandthat is currentlyexecutingand returns
control to the operator. The Human Interfacetask then waits at the semaphorefor
anotherunit.
This Controfc lasility allowsoperatorsto cancelcommandswhile the commandsare
executing.It is a valuablefacility that can be usedwith your commandswithout requiring
you to provide specialimplcmcntationcodc.

Human Interface User's Cuide

6-l

PROCRAM CONTROL

6.3 PROVIDING
YOUROWNCONTROL-C
MECHANISM
With somecommandsthat you write, you might want to overridethe defaultControl-C
mechanism.For example,supposeyou write a text editor. An operatorinvokesthe
editor with a Human Interfacecommandand then specifiesedit commandsto enter text
into a buffer and modify that text.
While usingthe editor, the operatordoesnot want a Control-Cch.racter to abort the
entire editingsession,destroyingtext in the editingbuffer that may havetaken hoursto
create. Instead,the operatormight want a Controlc to abort a singleeditor command
only. In order to provide thìs lacilì5,,your Human Interfacecommand(the editor) must
overridethe defaultControl-Cmechanismand provide its own codeto handleControl-C
entries.
To overridethe default Contol-C nìechanisn,you rìust changetlte senìaphofeto which
the OperatjngSystemsendsthe unit when the operatorentersa Control-C. By changing
the semaphoreto one thrt you create,you circumventthe Control-C task of thc Human
Interface. You can usethe Human Interlacesystemcall C$SET$CONTROL$Cto
replacethe Control-Csemaphore.
This systemcallchrngesthe callingjob's
Control-C
semaphoreto the semaphoreyou speci$. Tbere ìs only one parameterin this systemcall:
control$C$semaphore
whichis a token for your new Control-C semaphore.A sinldeunit
is sentto the new semaphoreeachtime a Control-Cis enteredfrom the terminal. A
completedescriptionof C$SET$CONTROL$Cis in the ExtendedíRtúX II Humatl
Interface SfstemCalls RefercnceManual.
IIyour commandreplacesthe defaultControl-Csemaphorewilh ils own,it shouldalso
seNicethat semaphore.It can do this either by creatinga task that waits continualÌyat
ihe semaphorefor a unit or by containinginlinc codc that pcriodicallychecksthe
semaphore.
ln either case,when a unit is sentto the semaphore,the command(or the task) must
pedorm the necessaryControl-Coperation.
The programflow oî sucha commandwould be:

6-2

Call CREATE$SEMAPHORE to createthe Control-Csemaphore.

Ifyou plan to crcatc a Control-Ctask to servicethc semaphore,call
CATALOG$OBJECT to catalogthe token for the semaphorein an objecr
directory.

lfyou plan to usea Control-Ctask,ìave the programcall CREATE$TASK to start
the Conlrol-C !ask.

Call C$SET$CONTROI-$Cto switchthe Control-Csemaphorekr the one jusr
created. Use the token for the semaphoreyou createdin Step 1 as input.

Iluman InterfaceUsels Guide

PROCMM CONTROL

Continuewith command
processing.
If youareservicing
the Control-Csemaphore
inJine,periodically
checkthesemaphore
(bycallingRECEIVE$UMTSwith rheno
wait oplion)to determineif it containsanyunits. lf youobtainanyunitstiom the
performthe necessary
semaphore,
Control-Cprocessing.

To servicethe Control-Cwith a task,theprogramflowof theControl-Ctaskcouldbe:
l. CaULOOKUP$OBJEC
f to obtainthe tokentbr the semaphore.
2. Do forever:
a. Call RECEIVE$UMTS(wirhrhewaitforeveroption,OFFFFH)ro obraina unit
from the semaphore.

b. Perform the operationthat must occurwhen the operatorentersa Control-C.
Each methodof se.vicingthe Control-Csemaphorehasadvantages
and disadvantages.
Ifyoul codeservicesthe Control-Csemaphorewith inline code,you can perform any
operationyou want, You canbranchto variouslocations,you can start new tasksrunning.
you can abort the command,or you canperform any other function that you wish.
However,in order to servicethe Control-Csemaphorewith in-Jìnecode,you must check
the semaphoreperiodically,to seeif it containsa unit. When doing this,you must ensure
that you placethe checksinsideall programloopsthat perform operationsan operator
might want to abort. Also, becauseyoìr can checkthe semaphoreonly periodically,you
cannotalwaysguaranteea quick responseto the Control-C.
Ifyou usea Control-C task,you canguaranteequick servicebecausethe tesk is always
waitingat the semaphore.However,becausea separateraskservicesrhe Conrrol-C,you
can perform only a limited numberofoperationsin responseto the Control-C.
.

The taskcall sendi{ rìessageto the command,but then lhe commandwould haveto
periodicallychecka mailbox. This hasthe samedisadvantages
as inJine servicingwìth
none of the advantages.

The taskcan deleteor suspeodthe command. However,the task hasno way of
knowingwhat operationsthe commandwasperformingwhenthe operatorentered
the Control-C. If the commandwasupdatingan internal table,deletingîhe command
c{ruldcorruptyour entirc lystcm- Suspendingthe commandcould allow the Contro!-C
task to interrogatethe command'sstate. The Control-Ctask could deletethe
commandif appropriate,or it could allov/thc commandto .un until it wassafc to be
deleted.

Onceyour commandassignsa new Control-Csemaphore,the semaphoreremains
assigneduntil either of the followingthÌngsoccur:
.

Your commandinvokesthe Human InterfaceC$SEND$COMMAND systemcall.
Invokingthis systemcall automaticallyrevertsback to the default Control-C
mechanism.To continueusingyour own Control-Cmechanism,invoke

Iluman Interface ùs€r's Cùide

6-3

PROCKA.M CÓNTROL

C$SET$CONTROL$C
(o switchbackto yourControl-Csemaphore)
immediately
afterinvokingC$SEND$COMMAND.
r

Your commandis deleted. When this happens,the Human Interfaceaùtomatically
reactivatesits defaultControl-Csemaphore.For example,oncethe exampletext
editor describedearlier in this chapterterminates,the Human Intedace resetsthe
semaphoreso that Controlc againbecomesactive.

6.4 A SAMPLECONTROL-C
TASK
Thissectionprovidesan exampleof a user-supplied
Cont.ol-Cmechanism.

+*+++***+***ìL*********

/***:l****:l*:l*ìl**************)t*)Y**:!*

TITLET

control$C$handler

ABSTRACT:
T h i s L a s k r . r a i t sa t a s e m a p h o r ef o r a s i n g l e u n i t .
If a unit is received, the culrerL job is Lerninated.
CALLINGSEQUENCE:
C A L Lr q $ c r e a t e $ t a s k ( . . . ,

@control$C$handler,...);

ALGOR]THM:
LOOKUP$OBJECT
for

the Control-C

seìrìaphore (should be catatoged
u n d e r ' S E l ' f A ' ;)

DO FOREVER;
wait for unit at Control-C semaphore;
if a unit ís rècèíwed, terminote the jÒb ucing cxitgiogjob;
END;
*******:l*********

**************:t*****x***)r***********:t**/
Figure 6-1. A CONTROLC Task Example (continued)

6"4

Human InterfaceUser's Guide

PROGMM CONTROL

hcctask:

D0;

'
$subritle ( conrro 1$C$handler , )
contro 1$C$handler :

PRoCEDURE
REENTR-ANTPUBLTC;

DECIaREtoken LITERALLY'SELECTOR'
;
(/rmx286/inclerror. 1it)
(/rnx286linc^i.
ext)
(/rnx286/inc/eíos. ext)

9include
$include
0include

/*
DECIARE
E$O(
locar$excep
unlÈs

local

varíables

LTTEMLLY
I.]oRD,
l,iORD,

TNFINITE9I,IATT

LITERALLY
TOKEN;

' OFFFFH',

sena - rqg lookupgobj ect ( SELECToR$0F(NIL,@(4,,SEMA,),INFINITE$WAIT,
@loca1$excep);
IF

1ocal9excèp o E$oK
THEN
CALL rqSexit$ioSj ob(loca19excep,NIl-,Gloca1$excep) ;

DO FOREVER;
units-rqqreceiwe$units
IF

( sena, 1, INFINITE$I,IAIT,

Qlocal$excep);
localgexcep : ESoK THEN
C A L L r q $ e x i t $ i o $ j o b ( 0 , N I L , G l o c a l $ e x c e p );

END;
END control $C$handler ;
END hcctask;

Figùre6-1.A CONTROLCTaskExample

Human Interface Uscr's (;uidc

6-5

7.1 oVERV|EW
This chapterdiscusses
the stepsthat you mustperform to createyour own Human
Interfacecommands.lt discusses
the necessaryelementsof a commandas well as how to
compile(or assemble)and bind your code(usingBND286).
To perlorm the operationsdescribedin this chapter,you must haveeither an Eo8ó-based
MicrocomputerDeveìopmentSystem(suchas a SeriesIV) or an iRMX ll-based system
that includesthe Human Intcrfacecommands.trither systemmust hav€an Editor,the
necessary
compileror assembler,
and the utility programs(suchas BND286).

7.2 ELEMENTS
OF A HUMANINTERFACE
COMMAND
Thissectiondiscusses
the rulesthateveryuserwrittencommand
mustobey.It also
suggests
someprogrammngpractices
to makecodingandusingyourcommands
easier.

NOTE
Whencodingyourcommands,
be carefulnot to duplicateCLI command
namessuchas,ALIAS andSUBMIT. If yougivea command
a CLI
commandname,youmustexecute
it with the full pathname,
for example,
rutjl:alias.
Otherwise,
rheCLI command
willbe executed
insteadofyour
commano.

7.2.1 ParsingThe CommandLine
Ifyou are goingto allow the operatorto enter parameterswheninvokingthe commàno,
the first thing your commandshoulddo is parsethe commandline. Chapter3 describes
the Iluman Intcrfacesystemcalìsthat you can use. To supportlìslsofparhnamesand
wild"cardedpathnames,the flow of a programrhat usesinput and output files shouldbe:
l.

Calì C$GBÌ $INPUT$PATHNAME to obtain the entire lìst of input pathnames.

Call C$GET$OUTPUT$PATHNAME to obrainthe D.eposirionand rhe enrirelisr
of outout Dathnames.

HumanlnterfaceUser'sCuide

1-1

CRE,dTING HUM.4.N INTERF,A.CE COMM,{NDS

Call C$GEISPARAMETER as manytimes as necessaryto get all the parAmeters.

remain:
Do until no more inputpathnames
a.

Call C$GET$INPUT$CONNECTIoN to obtain a connectionto the input file.

Call C$GET$OUTPLn$CONNECTION to obtaina connectionto the output
file.

Readthe informationfrom the input fìle, perform the commandoperations
basedon that input, and wite the informationto the output file.

Ca S$DELETE$CONNECTION(ExtendedI/O Systemcall) to deletethe
connectionsto the input and output files.

Ca[ C$GET$INPUT$PATHNAME and C$GET$OUTPUT$PATHNAME to
obtain the next input and output pathnames.

7.2.2AvoidingTheUseof CertainSystemCalls
Whenyouwrite thecodefor yourHumanInterfacecommand,
youcanuseanyof the
iRMX II systern
calls,dep€ndirgon the requilem€rtsolyour coulnand.However,some
jobs(thosejobsthatyou
systemcallsareintendedprimarilyfor usein system-level
configure into îhe Operating System rather than invoking as Humîn Interface

commands).In the descriptionsof systemcalls,the iRMX II systemcall reference
manualscontaincautionsconcerningthosesystemcallsthat you shouìdavoid using.
In particular,avoid iRMX II objects(and thei associated
sysîemcalls)that, by their use,
makeyour commandimmuneto deletion. Regionsand extensionobjects(describedin
îhe Extended.íRMX II Nucleut User'sGuide) are exampÌesof such objects. lf your
commandbecomesimmuneto deletion,a Control-C that an operatorentersto cancelthe
coúmand will haveno effect;the operator'sterminalmay alsolock when the command
finishesorocessins.

HumanInterfaceUsey'sGuide

CRXATINGHUMANINTERFACECOMMANDS

7.2.3 TerminatingThe Command
Whenthe operatorinvokesa command,
the OperatingSystem
loadsthecommandinto
memoryandcreatesanI/O job astheenvironment
in whichthecommandruns. (The
E tehded|RMX II E tenlle.lI/O SystemUser'sGuidediscusses
I/O jobs.) The operator
canusethe CLI BACKGROUNDcommand
to process
commands
h background
mode,
andat the sametime continueprocessing
anothercommand
in the foreground.In order
to finishprocessing
a foreground
command
correctly,anytaskin thecommandthatexits
mustdo soby callingEXIT$IO$JOB(anExtended
I/O Systemcall,described
in the
E tekd.ed
LRMXII Extended
I/O Ststeh CctlkRefercnce
Manual). This systemcall causes
theOperatingSystemto deletetheI/O job containing
the command,
thereforereturning
control!o lhe operalor-If thecommand
runningin the foreground
omitsthe callto
EXIT$IO$JOB,
theoperatormightnot be ableto enterfurthercommands.
To terminate
a command before it reaches its normal completion, th€ operator should €nte
CONTROL-C to abort a command running in the foreground or the CLI KILL command
to abort a command running in the background envhonment.

7.2.4 Include Files
When ìr'ritingthe codefor your commands,you must declareeachiRMX II systemcall as
an externalprocedure.Insîeadofwriting thesedeclarationsyourself,you can usethe
$INCLUDE statement.$INCLUDE statementsmake it possibleto includecodefrom an
efernal file into your program. The followinginformationmay be in an $INCLUDE file:
externaldeclarationsof systemcalls,Ìiteral definitionsof exceptioncodes,and common
literal definitionsthat you detlare.
the iRMX lI $INCLUDE liles are createdduring softwareinstallationand are locatedin
the |SD:RMX286/INC directory. There is an $INCLUDE file for eachsubsystem.This
file includesall the externaldeclaraaions
for all the sys[emcallsof the subsystem.For
example,the $INCLUDE file for the Human Interfaceis :SDrRMX286/INC/HLEXT. It
containsall the exiernaldcclarationsfor the Human Interfacesyslemcalls. To usethese
files,simplydeterminethe subsystem
that your commandrequiresand code$INCLUDE
stat€mentsfor the correspondingexternaldeclarationfiles into your sourceprogram.
You might alsorequireliteral definitionsof exceptioncodesso that you can refer to the
exceptioncodesby their mnemonicsinsteadofby their values(for example,E$MEM
insteadof 2H). After softwareinstallation,the :SDrRMX286/INC directorycontainsthe
ERROR.LIT file consistingof LITERAILY declarations.The file definesall the iRMX
lI conditioncode mnemonicsused. Refeî fo fhe Extended|RMX II Hardwareand Software
InstallatiokGuídefoî ll].formaîionaboutthe releasediskettesand the files containedin
them. Refer to the PL/M-28ó User'sGuìdefot informationabout the $INCLUDE

Human InterfaceUset's Guide

CREATINGHI]MAN INTERFACECOMMANDS

7.3 PRODUCING
AN EXECUTABLE
COMMAND
youmustproduceobjectcode
AJteryouhavewrittenthesourcecodefor yourcommand,
that can be executed in an iRMX lI environm€nt. This involves the {ollowing proccdure:

Compile(or assemble)
thecommand
Whenyou
usingtheappropriate
translators.
do this,ensurethatthe namesyouspeciryin $INCLUDEstatements
specirythe
correctdevices
anddirectories.

UsingBND286,bindthecodeto iRMX II interfacelibraries(andanyother
librariesthatyourequire)andproducea relocatable
objectmodulethatthe
OperatingSystemcanloadanyrvhere
in memory.The formatof the BND286
commandis:
BND286
&
coronand-narne,
&
:dir: other. Iib,
&
: SD:RlDt28 6/LIBIRIXIF* . LIB &; replace :r (c - CoMPACT,L : llRcE)
(DYIqAMICMEM(nin,nax)
( outpùt - pathnarìe) &
RCONFIGURE
) OBJECT
( STACK(
SEGSIZE
stacks ize) )

wherel

7-4

command-name

conìpletepathnam€of the lilc containingyour compiled(or
assembled)command. You can bind in severalfiles or lìbrariesat
this point, if necessary.

:dill

A genericlogicalnameyou createfor directoriescontaining
miscellaneous
libraaies.

other.lib

Any other files or librariesthat you needto bind with your
command,for example,PLM286.LIB.

oulpul-pathname

Completepathnameof the file in which BND286placesthe
commandafter binding.

stacksize

Siz€,in blt€s, of the stackneededby the corrnraodand any systen
callsthat the commandmakes. The Human Interfaceusesthis
valuewhen it createsa job for the command.Be surethe s!Ìck is
large enoughto handleboth userand systemrequirements.The
defaultvalueis 1200H Reîer tothe F.rtctu1e.1íRMX
II
Prcgamminq TechniquesReferehceMamral for information about
stackrequirementsofthe systemcalls.

mrn max

Minimum and maximumamountof dynamicmemory,in bltes,
requiredby the mmmand. The defaultvalue for both parameters
N Zero,

HumanInte aceUse/s Guide

CREATINGHUMANINTERFACECOMMANDS

Thecommand
usesthismemorywhenit createsiRMX II objects.
TheApplicationLoaderusesthemin andmarvalueswhenit loads
a job for thecommand.Be sure!ha!thesevaluesarelargeenough
to sadsrytheneedsofyour command
andsmallenoughto allow
the command to be load€d irto the opetatof's ùtenrory partition.

For example,
suppose
a sortcommand
requiresat least64Kb),tes
of dynamicmemorybut canuseanyadditionatdynamicmemory
for buffersto increase
performance.
Ifyou do not definea
maximummemoryparameter,
all ofyour dynamicmemory*ill be
allocated
to thesortcommand,
preventing
youfrom executing
othercommands
at thesametime. Therefore,assume
thatyou
wantto limit themaxvalueto lM byte. Yor-rshouldspecifu:
( DyNAr'fIOllU].l
( l000Oft, I00000H) )
RCONFIGURE
Be sureto considerthe followingfactorswhen calculatingthe
valuesfor min and max.
. The valueyou give for min and the memoryreqùiredhy the
Human Interfaceprogrammust fit into contiguousmemory.If
there is not enoughcontiguousmemoryfor them,you may not be
ableto load your command.
. The maxvalueshouldbe large enoughto ensureenough
memoryfbr commandsthat requestmemorydynamically.
The commandis now readyfo. execution.An operatorcan itvoke the commandby
enteringthe pathnameof the file contajnjngthe command(the output-pathnamein the
BND286cornmand).
I[you are usingan IntellecMicrocomputerDevelopmentSystemto compileor bind your
command,you must connectthe developmentsystemto your iRMX II applicationsystem
viù the iSDM monitor and usc thc Human IntcrfaccUPCóPY commandto copy the
boundcommandfrom the developmentsystemdisk to an iRMX ll secondarystorage
device. The UPCOPY command is describedn the Operator'sGuide To 'fhe Extended
iRMX II Human Interface.AJter you translèrthe boundcommandtoan iRMXII
secondarystoragedevice.an operatorcan invoke the commandby enteringits pathname
at the iRMX II terminal.

Hunan InterfaceUserrsGuide

8.1 oVERVIEW
The Human Interfaceis a conligurablelayer of the OperatingSystem.It containssel,eral
optioN that you can adjustto meetyour specificneeds.To help you make configuration
choices,Int€l providesthree kinds ofìnformation:
.

A list ofconfigurahleoptions

Detailed informationaboutthe options

Proceduresto allow you to specilyyour choices

The rest of this chapterdescribesthe configurableoptions. For inlormation on the
second and third categories,refer to the Errendrd iRlvlx II Intetuctive ConfrguratíonlJtiliîl
ReferenceMunuù.
Human Interfaceconfigurationconsistsof two parts:residentconlìgurationand
nonresidentconfiguration.
Residentconfigurationinvolvesconfiguringthe portion of the Human Interfacethat
residesin systemmemoryat all times. This confìgurationtakesplaceduring the
configurationof the entire OperatingSystem,whenyou run the InteractiveConfigùration
Utility to adjustpa.ameters,includeor excludelayersofthe OperatingSystem,and
generalean execufableversionof the OperatingSystem. You cannotchangethe r€sident
configurationwithout reconfiguringthe entire OperatingSystemNonresidentconfigr-rration
involvessettingup an iRMX II directorystructureand placing
informationaboutterminalsand usersinto iRMX II files. The nonresidentconfiguration
informationmust be presentwhen the applìcationsystemstartsrunning,but it can be
modifiedwhile the systemis running. Changesto terminalconfigurationtake effectthe
next time you initializeyour applicationsystem.Changesto userconfigurationstake
placewheneverthe affecteduserslogon to the applicationsystem.

8.2 RESIDENT
CONFIGURATION
When you perform the residentHuman Interfaceconfiguration,you can modily
parametersof the Human Interfacethat afîect all Human Interfaceusers.Theseinclude:

Human InterfaceUser'sGuide

8-l

CONFIGIIRATION OF THE HUMAN INTERFACE

lnformation aboutthe Human Interface'sinitial job, suchas minimum and maximum
memorypool sizeand whetherjobscreatcdby the Humao Interfaceexpectto usethe
80287Numeric ProcessorExtension.

Information aboutthe residentuser(if applicable),includingterminal name,terminal
device,user ID, madmum prioriry, pathnameof initial program,and defaultdire.tory.
The residentusercan be a normal residentuserwho hascontrol as soonas the system
is bootedor a recoveryresidentuserwho gahs control only when initializationerrors
occur in the configurationfiìes. A systemcan haveonly one residentuser.

Information about thejobs createdby the Human fnterface,includingminimum and
maximummemorypool sizes.

lnitial sizeof the buffer that the Human Interfaceuseswhen constructingcommands.

Maximum lenglh of a commandpathname.

List of diectories that îhe Human Tnterfaceautomaticallysearches,in order, when
trying to find a command.

Pathnameofthe di.ectoryassignedto the logicalname :SYSTEM:and a list of
pathnamesand the logicalnamesthat you want the Human Interfaceto assignupon
initialization.

Information aboutthe defaultresidentinitial programincludingwhetherthe fluman
Interfaceusesthe Intel suppliedCLI as ìts defaultinitial programot a customized
CLI. Ifa customizedCLI is included,you mustalsospecifyits pathname.

Information aboutuserextensions.Ifyou specilythe Intel-suppÌiedCLI as the
residentinitial program,you car spcciîythe pathnameofthe CLI user efension that
is to be incorporated.The defaultCLI doesnot containuserextensions.

8.3 NONRESIDENT
CONFIGURATION
The nonresidenî
configuration
involvesspecilying
informationaboutthe terminalsand
usersthataccess
a multi-access
Humanlntertace.
For cachterminalin thesystem,
youmustspecify:
r

Termiaaldevice

Terminaltlpe (name)

The usernameassociat€d
w;th a staticlogon t€rminal

For eachuserin th€ system,yolt shouldspecify:

8-2

Logon name

User ID

EncrvoterlPassword

HumanInterfaceUset'sGùide

CONFIGURATION
OF THE HUMANINTERFACE

Mhimum andmaximummemorypartitionsizes

Defaultdfuectory,
whosepathnameis assigned
to the logicalname:HOME:

Pathname
ofthe initialprogam (optional)

Ma\imumjob priority

8.4 INITIALIZATION
ERROR
REPORTING
During the confìgurationprocess,you can ele.t to havethe systemreport Human
Interfaceinitializationerrors. Ifyou respond"Yes"to the Report TnìtializationErrors
(RIE) parameteron the "Nucleus"screen,the OperatingSystemreportsinitialization
errors from all subsystems.On encounteringa Human Interfaceinitializationerror, the
OperatìngSystemreturnscontrol to the iSDM monitor after writing the following
messageto the iSDM consolel
Hunan Interface Initialization

Error:

If Report InitializationErrors is not configuredinto your systemor the iSDM monitor is
not present,the initial Human Interfacetask plàcesthe Human InterfaceID code (4) and
the correspondingerror code into the first two wordsofthe Nucleusdata segment
(lEo:0000H). It then goesinto an infinite loop.
A completelist of iRMX lI error codescan be found in AppendixA ol fhe Operutor's
'I
Guírle 7o he Extended|RMX II Human Inteíace.

Human InterfeceUs€t's Guide

8-3

4.1 TYPEDEFINITIONS
The Extended
iRMX ll OperatingSystem
recognizes
thesedataq?es:
BYTE

An unsigncd,
eight-bit,binarynumber.

WORD

An unsigned,
16-bit,binarynumber.

DWORD

An unsigned,
32-biîbinarynumber,occupying
twocontiguous
wordsof memory.

INTEGER

A signed,
two-byte,
binarynumberstoredin two'scomplement
form.

POINTER

Twowordscontaining
thesegment
selectorandan offsetinto that
segment.Theoffsetis in the WORDwith thelowestaddress.

SELECTOR

A l6-bit quantitythatis equivalent
portionof a
to the selector
POINTER.

TOKEN

A wordcontaining
thelogicaladdress
of an object.Tokensare
selectors
thatreference
an entryin a descriptor
table.The entryin
lhe descriptor
tablecontainsthephysicaladdress
of theobject.

STzuNG

A sequence
ofconsecutive
byteshavingthestructure:
length BYTE,
chars (2s5) BYTE;
The first byte containsthe lengthof the string (the numberof
succeeding
bytes).
The subscriptol the charsfield (255)is the marrimumnumber of
bytesin any string. Note, thst somesystemcallslimit stringsto
lengthsshorterthan 255 bytes. A zero count specifiesa nùll string.

STRING$TABLE

Hùman Interfare

A count bytefollowedby a sequenceof consecutivestrings. The
valuecontailed in the countbyte is the number of stringsin the
rest of the stringtable. Sincethe string tablecontainsonly a single
byte in which to storethe count,îhe ma\imum numberof strings
that a stringtablecan containis 255. A zero coùnt specifiesa null
string table.

-À-t

8.1 STRINGFORMAT
The EnendediRMX II OperatingSystemusesstructures
calledstringsto storegroupsof
ASCIIcharacters
(suchaspathnames).
The OperatingSystemassumes
a stringto be a
seriesofconsecutive
bytesbrokeninto twoportions:a countbyteandtextbytes.The first
bytein the stringis thecountbyte;its valueis setto thenumberofbytesin the text
portionof the string.The textbytescontainthe substance
ofthe string.
TheOperatingSystemalsousesanotherstructurecalleda stringtable.A stringtable
consistsof a count hyte and a seriesofconsecutivesrrings.As wiih rhe string,the firet
byte in the stringtable is the counrbyte; its valueis set to the number of stringsin the
string table. The diagramin Figure B-1 showsthe string$tableparameterformat.

B Y T E : n u m b eor f e n t r i e s( n )
S T R I N G :s t r i n g1
S T R I N G :s t r i n g2
S T R I N G :s t r i n g3

S T R I N G s: t r i n gn
Extra space, if any

FigureB.l. StringTableFormat

Human InterfaceUsefs Gùide

B-1

APPENDIXBr STRJNCT BLE FORM^T

EXAMPLEI
Assumeyouwishto generate
a stringtablecontaining
thewordsIIAPPY,GI-AD,and
SAD. The following declarations would be needed:
DECIARE
p$tablè(*) BYTE DATA(3,
5 , 'HAPPY',
4 , ' G I A D ',
3, 'SAD' ) ;

R_t

NUMBER
OF STR]NGS*/

HumanlnterfaceUser'sCuide

$INCLUDEstatement7-3
.1-6
? 1-6

A
abortingcommandexecution6-1
acccssing
thevaluesin R?ERROR2-5
actionsoî the Humanlnterîacewhenstarted1-1
AFTER preposition4'2
AIIAS 1-2
amPersandcharacter(&) 3-4
avoidingsystemlevelcommandsin Human Interfacecommands7-2

B
bindinga HumanInterfaceCommand,
example7-4
bindinga userextension2-10
BND2867-1,4

c
C$BACKI]P$CIIAR3.6
C$CREAIE$COMMAND$CONNECTION
5-1
C$FORMAT$EXCEI'TION
4.5
C$GET$CI{AR3-6
C$GET$INPUT$CONNECTION
4.1
C$GET$INPUT$PATHNAME
3.5
C$GET$OUTPUT$CONNECTTON
4-2
C$GET$OUTPUI$PAI'HNAME3-5,11
C$GET$PARAMETER3-5
C$SEND$CO$RESPONSE
4-3
C$SEND$COMMAND5-2
C$SEND$EO$RESPONSE
4-4
c$sET$coNIRO$C 6-2
CATALOG$OB]ECT6-2
cicumflex 3-20
CLI extensions
2-4
command
connection5-1

Hùman InterfaceUsefs Guide

Index-l

INDEX

command
connection,
creating5-1
command
line interpreter(CLI), description
of 1-1
commandline,p.iority 5-3
command
name,obtaining3-20
command$except$ptr
5-3
command-Iine
structure3-1
command-name
3-2
commentcharacter3-4
communicating
with the operator'sterminal4-3
configuring
theHumanInterface8-l
continuation
character3-4
continuationcharacter
5-2
continuation
markfor CLI commands2-3
Control-C6-1
CREATE$SEMAPHORE
6-2
CREATE$TASK 6.2
creatinga commandmnnection5-1
creatingI/O connectionsl
creatinguserextensions
2-4
customCONTROL-Cmechanism6-2
olstominitialprogram2-11

D
data t)?es A- 1
deletinga commandconnection 5-3
Deviceand volumemanagementcommands,[st of 1-2
dynamiclogon terminals l-4
dynamicmemorypartitions 1-4

E
E$CONTINUED5"2
elements
of a HumanInterfacecommand7-1
error handlingin the CLI 2-5
example
BND2867-4
CONTROL-Ctask 6-4
string B-2
userextension2-5
examplecodeusingcommandconnections
5-3
exampleprognm flo\{ for a CONTROL-Cmechanism
6-2
exampleprogramflowfor a CONTROL-Ctask 6-3
examples
COPY3

Ind€x-2

Human InterfaceUsertsGuide

INDEX

FORMAT3
qùotingcharacters3-5
UPCOPY 3.3
EXIT$IO$JOB2.12
EXIT$IO$JOB7,3
efensions,of the CLI 2-4

F
featuresof the CLI
Aliasing2-l
Background
processing
2-2
1/O rcdireztion 2-2
Lioe-editing2-1
Session
history2-2
Set 2-2
featuresofthe HumaoInterface1-2
Filemanagement
commands,
list of 1 2
formatof a string B-l
formattingmessages
basedon exception
codes4-4

G
GeneralUtility commands,
list of 1-2

H
HISTORY 1-2
how CONTROL-C works 6-1
how the CLI parsescommandlines 2-3
how to createuserextenstions2-4
Human lnterfaceCalls
Command-parsing
systemcalls 1-3
I/O and messageprocessingsystemcalls 1-3
Human InterfaceCallsCommand-processing
systemcalls 1-3
Human InterfaceCallsProgramcontrol systemcall 1-3
Human Intedace,configuring 8-1
Human Interface,featuresof 1-2

I
initialjob 8-2
initialprogram
standard1-5

HumanhterfaceUsefsGuide

Index-l

INDEX

initialprogram l-1,2
initialprogram2-11
initializationerrorreporting8-3
initialization of the CLI 2-2

inpath-list3-2
inputandoutputconnections
4-1
invokingCLI commands2-3
iRMX.NET 1-4

J
JOBS6-1

K
ke).llord = value-Iistor keyrvord(value-list) 3-13
ketq'ordvahre-list3-3,13
keyword(valueJist)
3-3
keyxord=value-list
3-3
KILL 6.1

L
I-AN support1-4
Lineterminatorcharacter3-3
loggingoffa terminal 1-5
logicalname
SYSTEM 8,2
logon 1-3
logonfacility 1-3

M
multi-accesssupport
1-5
muldpleterminalsupport l-5

Index-4

Humanlnterfa.eUser'sGuide

INDEX

N
nehvork aqless 1-4

Nonresident
configuration8-1,2
nonrcsident
informationfor eachuserin a system
Encry?ted
Password8-2
default8-3
Logonname 8-2
Marimumjob priority 8-3
Minimumandmaximummemorypartitionsizes8-3
Pathname
of theinitialprogram(optional)8-3
UserID 8-2
nonresident
informationfor terminals
fhe usernameassociated
with a staticlogonterminal8-2
nonresident
user 1-3
nonstandard
command
iines 3-17

o
obtainingthe commendname2o
ourpathiisr 3-3
OVER preposition 4-2

P
paÉmeters3-3
parameters
in a BND2Eócommand7-,1
parsinginputandoutputpathnames
3-6
parsingnonstandard
command
lin€s 3-15
parsingotherparameters3-12
parsingthecommandline
7-l
parsingthecommandline 3-5
pathnames
wild-card1-6
preposition
after 3-2
ove. 3-2
to 3-2
prepositior3-2
priorityofthe command
line 5-3
purposes
of C$GET$PARAMETER
3-12

o
quotingcharacters3-5

Human InterfeceUsels Cuide

Index-5

INDEX

R
R?ERROR2.5
RECEIVE$UMTS
ó.3
Residettconfiguration8-1
residentHumanInterfaceCommands1-2
residentuser 1-3
restrictions
on custominitialprograms2-12
ruÌesfor custominitialprogram2-11
rulesfor usingGET$INPUT"andGET$OUTPUT$PATHNAME
3-7

s
semicolon
character
(4
sET 1-2
standardinitialprogram 1-5
staticlogontcrminals1-4
stepsfor invokingcommands
from a program5-1
stringexampleB-2
stringformat B-l
structure
message
for errorcodes4-5
switching
to anotherparsingbuffer 3-l8

T
terminals
dynamic logon 1-4
togging off 1-5
staticlogon 1-4
supportfor multipl€ 1-5
terminatinga Human Intedace command 7-3
three procedurcsofa CLI extenstion
epilogue 2-5
initialization 2-4
processing2-4
t'?es of data A-1
rypical programming scenaio 4-2

Index-6

HumanInt€face Usefs Guide

INDEX

U
uset
non-resident1-3
residenr 1,3
userextension
binding 2-10
userextensionexample2-5
usingthe commandconnertion 5-2

V
value-list3-3,12
varialionsofthe slandardcommand
line 3-16

w
wild card characters3-10
wild cards
asterisk 3-10
questionmark 3-10
wild-cards l-6
writing an executablecommand 7-4

HumanlrterfaceUser,sGuide

Ind€x-7

intel'
E X T E N D EiDR M X@II

APPLICATION
LOADER
U S E R 'G
SU I D E

IntelCorporatron
3065Bowers
Avenue
SantaClara,Californa 95051
o 1988.IntelCorporaton.All RiqhtsReserved
Copyriqht

This manualexplainsthe operationof the ExtendediRMX II Application Loader.
Application programmerswho want to load programsfrom secondarystorageùnder the
control of extendediRMX II tasksshoùldread this manual. I'his mamralexplainsonly
the generaloperationsof the ApplicationLoader. For detaileddocumentationon
extended iRMX II Application Loader system ca17s,
consvlt the Ertendcd iRlvIX II
Applícation Loader Ststefi CaILtReferchcemanual.

READER
LEVEL
This manualassumesknowledgeofthe iRMX II OperatingSystemand terminolog/
associated
with it.

CONVENTIONS
All iRMX II systemcallsbeginwith oneof two standard
prefixes:RQgor RQES.When
referringto the systemcallsthatbeginwith RO$,thismanualusesa shorthand
notarion
andomitstheprefix. For example,
S$OVERI,AYmeansRQ$S$OVERLAy.The actual
PL/M-286externalprocedure
namesusedto invokethesesystemcallsareshownonlyin
lhe E'rtended|RMX II ApplicationLoaderReference
manual,whichlisrsthe detailedcalling
sequences.
Whenreferringto systemcallsthatbeginwith RQE$,thismanualspellsout thecomplete
names,includingthe RQE$ charactcrs.
There are somesystemcallswhosenamesare idenrical€xceptfor the RQ$ or RQE$
prefix (for example,the ApplìcationLoader systemcals RQ$A$LOAD$IO$JOBand
RQE$A$LOAD$IO$JOB). The differencebetweentwo similarlynamedsystemcallsis
that the RQ$ versionoperatesas ir did under rhe iRMX 86 OperatingSystemand is
availablefor compatibiJity.The RQE$ versionis updatedto supportnew iAPX 286
features,suchas 16M byte memorypools. Unlesscompatibitty with iRMX 86 systemsis
an issue,Intel recommendsthat you usethe systemcall with the RQE$ prefaceinsteadof
the one with the RQ$ preface.

Applicationlîader Usefs Guide

lll

CONTENTS

ApplicationIÍader User'sGuìd€

ApplicationLoaderUseasGuide

CHAPTER
1

INTRODUCTION
TO THE
IRMX6II APPLICATIONLOADER

1.1OVERVIEW
The ExtendediRMX II ApplicationLoader,a configurablelayer of the iRMX ll
OperatingSystem,loadsprogramsunderthe control of iRMX II tasksor tasksthat are
part of appljcationprograms.
The ApplicarionLoaderprovidessystemcallsthat load programsfrom secondarystorage
into memory. Usingthe ApplicationLoader providesseveraladvantages:
.

Allows paogramsto run in systemswith insufficientm€moryto aocommodateall
programsat one time.

Allows programsthat are seldomusedto resideon secondarystoragerather lhan in
memory.

Makes it easierto add new programsto the system.

The Application Loader alsoenablesyou to implementlargeprogramsby usilg overlays.
For example,supposethat your applicationsystemincludesa large dataprocessor.By
dividingthe dataprocessorinto severalparts,you can avoidkeepingthe entire data
processorin memory. One ofthe parts,calledthe root, remainsin RAM as long as the
dataprocessoris running. The root usesthe ApplicationLoader to load the othef parts,
calledoverlays,wheneverthey are needed.
This chapterwill helpyou understandthe capabilitiesof the Application Loader by
providingbackgroundinfornation.
After readingthis chapter,you shouldbe ableto understandthe systemcallsdesc.ribed
in
the Ertetuled iRtúX Application Loader S$tem Calk ReferenceManual.
Readersfamiliar with the iRMX 86 ApplicationLoader may find it helpfulto start by
readingAppendixB, which describesthe main differencesberweenthe iRMX 86 and
iRMX II AoDlicationLoaders.

Application tóader Usrrts Gùide

l-l

INTROI}IICTION TO TIIE iRMX@II APPLICATION LO^DER

1.2 APPLICATION
LOADER
FEATURES
Severalfeatures: deviceindependence,
synchronous
and asynchronous
systemcalls,
overlaidpfoBrann supporqanrJconfigurabiliry,make rhe iRMX II Applicariontnader
valuablein any applicationsystemthat loadsprogramsftom secondarystorageinto RAM.

1.2.1 DeviceIndependénce
The Application Loader can load objectcodeftom any deviceii the devicesupports
iRMX II namedfiles,and if an iRMX 1I devicedriver ìs available.Scc thc Extended
|RMX II Interactive Co frguration Utílit! RefercnceManual for a cofiplete list of Intel
supplieddevicedrivers

1.2.2 SynchronousAnd AsynchronousSystemCalls
The Application I-oaderprovidesboth synchronous
and asynchronous
systemcalls. Ifyou
want your tasksto explicitlycontrol the overlappingofprocessingwith loadingoperations,
you can useasynchronous
systemcalls. Ifyou prefer easeof useto explicitcontrol,you
can usesynchronoussystemcalls.

1.2.3 SupportForOverlaidPrograms
The Application Loader containsa systemcall explicitlydesignedto simp]ìIythe process
ofloading overlaymodules. By usingthe S$OVER[-AY systemcall,youÍ programcan
easilyload overlaymodulescontainedin the sameoverlaidobiectfile.

1.2.4 Configurability
The Application Loader is configurable,that is, you can selectthe featuresof the
ApplìcationLoader to meetyour exactneeds.For more detailsseeChapter3 and the
betenlcd |RMX II Intetucùve Configutution Utilit! ReJerence
ManuaL

1.3 PREPARING
CODEFORLOADING
yourcodesothattheApplicationLoadercanloadit, firstusean 80286
To process
translatoror assembler
(e.g.,PLM286,ASM286)to producelìnkableobjectmodules.If
yourcodeusesonlyUDI systemcalls,it canbe in anymodelof segmentation.
If it uses
anyotherlayerof iRMX II, theSMALL modelof segmentation
is not supported.

t-2

ApplicationLoaderUser'sGuide

INTRODUCTION
TO THE iRMX@II APPLICATIONLOADER

Afler lranslalingyour code,you must useBND2Eóto producea load file readyto be
loaded. The load file must be an OMF-286SingleTask Loadable(STL) objectfile with
LODFIX records. This kird of load filc is produccdby BND286 usingthe
RCONFIGURE control. STL format is the only objectcodeformat supportedby the
Application Loader. LODFIX recordscontainthe locationsof the selectorsthat are to be
updatedafter loading. LODFIX recordsare necessary
becauseof the way the iRMX ll
OperatingSystemfunctions.
BND286assumesone I-ocalDescriptorTable (LDT) per task,and therefore,assigns
descriptortable entriesto the applicationprogramin successive
LDT slots. The iRMX II
OperatingSystemcannotensurethat the samedescriptortableentrieswill be allocatedto
the applicationprogram,in fact it allocatescDT slotsinstead. LODFIX recordsare
requiredto allow the Application Loader to replaceeachselectorin the objectfile with
the new GDT selcctordssignedat randomby the iRMX II OperatìngSystemat load time.
You can usethe Human InterfaceIHI) DEBUG commandto determinewhich GDT slors
were allocatedfbr your program. For more detailsseethe DEBUG commandin the
Opemtor'sGuide To The futended |RMX II Human lnteface.
Example:
The followingexampleillustrateshow an STL objectfile can be produced. It assumesthat
the directoryattachedas :LANG: containsthe compilerand the binder, and that the
directoryattaohedas rLIB: containsiRMX II interfacelibraries. Assumethat the source
codefor the programis locatcdin a PL/M-286 filc namcd MY PROG.P28.This program
adheresto the COMPACT modelof segmentation,
and thereforevr'illbe linked to the
COMPACI interfacelibrary of ìRMX II (RMXIFC.LIB). To producean objectmodule
from the codein MY PROG.P28,usethe followingseqù€nce:
PLM286MY_PROC.
P28 COMPACT
BND286&
MY_PROG,
OBJ, &
: L A N G : P L M 2L8I6B., &
:LIB:RMXIFC.I-IB
&
oBJECT(MY
PROG)SECSIZE(STACK(+500H)
) &
( DYÌ{MTCMEM
( 5000H, 10000H))
RCoNFtGURE
Upon completion,the objectmodule(MY PROG) is readyfor loading. The next two
sectionsdiscussthe SECSIZtr control and DYNAMICMEM option ofthe
RCONFIGURE control in more detail.

Application
toaderUser'sGuide

t--'!

fNTRODT]CTÍONTO THFJiRMX@II APPI,ICATIONI]OAI}T]R

1.3.1 SegsizeControl
The SEGSIZE control shouldcontainthe stacksizerequiredby your programand the
iRMX II laycrsuscd. You must adjustthc stacksizcof your programto accommodate
the stackrequirementsof the highestiRMX II layer used. Table 1-1lists the stack
requirementsof eachlayer. Note that theserequirementsare in addition to the stacksize
neededfor your program. The valuegivenas the minimum stacksizeincludesthe
requirementsof all lower layers,e.g.,ifyou useNucleus,BIOS and EIOS, you shouldadd
550 bytesto the stack.

Table l-1, iRMX@II StackSize
Ef6ndediFMXll Layer

M nimumStackSìzs
250bytes
350bytes
550byles
70Obyl€s
150Obyt€s
1750bytss

'|.3.2 Dynamicmem
Option
DYNAMICMEM is an oprionof îhe BND2[36
RCONFIGUREcontrol.TheApplication
Loîder ensures
thatyourprogramhasenoughdynamicmemoryonceit is loadedand
running.To do this,BND286allowsyouto specifythe amountof memoryyourprogram
wìll allocatedynamically.
Thevaluespecified
by MIN ìs alwaysavailable
for your
program,whilethevaluespecifìed
by MAX allowsyourprogramto borrowfrom iîs
parent.Notethatthesetermsapplyonlyfor progmmsthatareloadedasI/O jobs,thatis,
usingA$LOAD$lO$JOB,
RQE$A$LOAD$IO$JOB,
S$LOAD$lO$JOB,
or
RQE$S$LOAD$IO$JOB,

l-4

Applicationl-oaderUserrsCuide

2.1 oVERV|EW
The Application Loader systemcallscan be dividedinto three categories:
.

RQ$ and RQE$ systemcalls

I/Ojob and non-I/O job systemca[s

Synchronousand asynchronous
systemcalls

2.2 RQ$AND RQE$SYSTEMCALLS
The Application Loader hastwo systemcsllsprefacedby RQE thar allow you to speciry
memorypools up to 16M bytes(usingDWORDSfor pool parameten). For eachRQE
systemcall there is a similar call prefacedby RQ Int€l recommendsthar you usethe
RQE versionto allow you to take advantageof the iRMX II fearures.The RQ version
allowsyou to specilypoolsup to 1M byte only (usingWORDSfor pool parameters).The
followingare the systemcall pairs:
RQ$AXiLOAD$-tO$JOB--RQE$A$LOAD$IO$JOB
RQ$S$LOAD$IO$JOB..RQE$S$LOAD$IO$JOB
(When refe.ring to the rystemcallsthat beginwith RQ$, this manualusesa shorthand
notation and omits the prefiy.)

2.3 r/O JOBANDNON-|/OJOBSYSTEM
CALLS
An l/O job is ajob that providesthe environmentfor usingthe E\tended I/O System
(EIOS). A task can useEIOS systemcallsonly if it is runningin an I/O job environment.
Other than the A$LOAD systemcall, all AppticarionLoader systemcallsmust be invoked
within an I/O job environment.
If you are unfamiliar with l/O jobs, refer to the Extended|RMX II ExtendedI/O System
User'sGuíle for details.

Applicationlrader ltserJsGuide

2-l

APPLICATION LOADER SYSTENÍCALLS

2.3.1l/O JobSystemCalls
The iollowing systemcallsload programswithin I/O jobs:
A$LOAD$IO$JOB
RQE$A$I-OAD$IO$JOB
S$LOAD$IOSJOB
RQE$S$LOAD$IO$JOB
When one of thesesystemcallsis issued,the ApplicationI-oadercreatesan I/O job in
which the initial task is a part of the Application Loader that loadsthe program. The
loadedcodeis anothertask in the newjob. Once the codeis loaded,the Application
Loader task terminatesitself,unlessthe new programcottains overlays.In this casethe
Application Loader taskwaits for requeststo load new overlays.
Pool Size tor lhe New Job
Wlen creatingan I/O job the ApplicationLoader mustdeterminethe sizeofthe I/O
job's memorypool. The Application Loader usesthe followinginformationto compute
the sizeof the memorypool for the new I/O job:
.

The pool$min input parameter,as a numberof 16-byteparagraphs.

The pool$maxinput parameîer,as a numberof 16-byteparagraphs.

A Loaderconfigurationparameterspe.ifyingthe defaultdynamicmemory
requirements. (Reîer to the Erte ded íRMX II Interactive Confguntion Utilitl
Reference
Manual îor informationaboutconfiguringthe Loader.)

Memory requirementsspecifiedin the targetfile by usingthe RCONFIGURE control
ofBND286 when creatingthe objectfile.

The Loader givesyou two optionsfor settingthe sizeofthe I/O job's memorypool:
1.

You can setboth pool$minand pool$maxto 0. Ifyou do this, the l-oader decides
how large a memorypool to allocateto the new I/O job. The Loader usesthe
requirementsof the targetfile and the defaultmemorypool size-establjshed
when
the systemis coniigured-to makethis decision.Unlessyou haveunusual
requirements,you shouldchoosethis option.

You can use either pool$minor pool$màÌ to overrìdethe Loader'sdecisionon pool
size. If the valueyou enter in pooÌ$minìs lessthan what is requiredto ìoad the fìle,
the Application Loader ignoresyour input and setspool$minto the minimum
amountof memoryrequiredby your file.

lfyou set pool$mtu\to 0FFFFFH, the createdl/O job hasunlimitedmemoryborrowing
from its parent.

Applicationl-oaderUseis Guide

APPLICATIONLOADERSYSTEMCALLS

You shouldbe awarethat thc pool sizeparametersin Application l,oader systemcallsare
specifiedin 16-blteparagraphs;however,the pool parametersin the RCONFIGURE
control ofBND286 are enteredin BYTES.

2.3.2 Non-l/OJob SystemCalls
A$LOAD docanot crcatean I/O job. Instead,the ApplicarionLoadef rasktlìar loads(he
programis runningin the contextof the caÌler'sjob. The Application Loader doesnot
createa task for the loadedcode,but merelyplacesit in memory, If you want this codeto
run, you must explicitlycreatea task for it usingthe Loader ResultSegmentthat you
receiveon completionofloading. For more detailson the Inader ResultSegment,see
the Ertehded íRMX II Applîcatíon Loeder SystemCalls RefercnceManLral. Becauseno I/O
job is created,you can useA$LOAD in systemsthat were mnfiÉiuredwithout the EIOS
layer.

2.4 SYNCHRONOUS
ANDASYNCHRONOUS
SYSTEM
CALLS
TheiRMX II ApplicationLoaderprovidestwo rlpesof systemcalls:synchronous
and
asynchronous.Synchronous
callsreturn control to the callingtask after all operationsare
completed.Asynchronouscallsare executedconcurrentlywith your code.

2.4.1Synchronous
SystemCalls
Thesesystemcallsreturnto thecalleronlyafterthe servicehascompletely
finished,that
is,whenloadingfinishesor terminates
dueto an error. In thefirst case,an E$OKcodeis
returnedto theczdlervia the exception
pointerspecified
whenthecallis invoked.In the
secondcase,an errorcodeis returned.Thesynchronous
systemcallsare
S$LOAD$IO$JOB
RQE$S$LOAD$IO$JOB
S$OVERLAY
2.4.1.1RO(E)$S$LOAD$|O$JOB
Thesetwo systemcallsloadthefile specified
in the PATH$NAMEparameterandqeate
an I/O job asthe environment
for theloadedcode.Eithercallcanimmediately
startor
delayexecution
of theloadedcode,depending
on the TASI($FI-AGS
inputparamerer.If
delayedexecution
is specified,
START$IO$JOB
mustbe calledafterrheApplication
Loaderhassuccessfully
returnedandyouarereadyto startthe p.ogram.Another
pa.ameter,RESP$MBOX,
serves
astheexitmailboxfor the newlycreatedI/O job- The
EIOSsendsan exitmessage
to thismailboxwhentheloadedprogram(contained
within
thenewlycreatedI/O job) terminates,
by callingEXTT$IO$JOB.
For moredetailssee
CREATE$IO$JOB,START$IO$JOBanrl EXIT$IO$JOBin the -eúenledLRMXII EIOS
Svstemcalh Referchce
m nual.

Applicationl-oaderUser'scuide

APPI,ICATIONLOADERSYSTEMCALLS

2.4.1.2S$OVERLAY
subsections
of a program.These
The termoverlayreîersto logicallyindependent
subsections
arenot all presentin memoryat thesametimeduringprogramex€cution.
programsubsections
(andnot the entireprogram)usememory
Because
onlyexecùting
spaceat a givenphaseof programexecution,
usingoverlays
canreducethe memoryspace
requiredfor a programto execute.
youmustuseOVI286(the
To correctlycreateprograms
with overlays
on an Intel system,
80286overlaygenerator)to producetheobjectfiles. TheApplicationLoaderassumes
thatyouhavefollowedtheseruleswhenwritingyouroverlaidprogram.
.

The root ís alwayspresentin memory.

No overlay,excepttheroot,maybepresentin memoryunlessits parentis presentin

The onlypossible
request,from anygivenoverlay,is thata descendent
(in the tree)
overlaybe loaded.

Any previously
loadedsiblingis no longeraccessible
oncean overlayhasbeenloaded.

No assumptions
aremadeaboutthepreservation
of dataacrossmultiplerequests
to
load the sameoverlay.

S$OVERI-AY is usedwheneverthe loadedprogramrequiresthat a new overlaybe
presentin memory. This call can be usedonly by an overlaidprogram. It can be issuedby
any overlay(includingthe root) to load any ofits descendents.Although OVERLAY is
synchronous(i.e.,returnsor[y on completionofservice),it can be usedin conjunction
with the asynchronous
ApplicationLoader systemcalls. That is, A$LOAD$IO$JOB can
Ioad the file containinglhe programand S$O\.ERI-AY can load the required overlayinto

memory.

2.4.2Asynchronous
SystemCalls
Each asynchronous
systemcall hastwo parts: sequentialand concurrent.The sequential
part bchavesin much the samefashionas the fully synchronoussystemcalls. Itverifies
parameters,checksthe file to be loaded,and preparesthe concurrentpart of the sysîem
call. If any problemis detectedduringthe sequentialpîrtt an error codeis returnedto
the callervia the exceptionpointer and the concurrentpart is not started. If no error is
detected,an E$OK codeis returnedto the caller and the concurrentpart is started.
The concur.entpart runs as an iRMX II task. The task is madereadyby the sequential
part ofthe call and runs only when the priority-basedschedulingof the iRMX II
OperatingSystemúes it control of the processor.The concurrentpart also returnsa
conditioncode aspart of a result segmentthat is sentto the responsemailboxspecified
whenyou invokean asl,nchronous
Application Loadercall.

2-4

Applicationt oaderUsefs Guide

APPLICATIONLOADERSYSTEMCALLS

The asynchronous
callsar€ split into two parts !o improvc pcrformancc.The functions
performedby thesecallsare somewhattime-consuming
be.ausethey involvemechanical
devicessuchas disk drives. By performingthesefunctionsconcurrentlywith othcr work,
the ApplicatìonLoader allowsyour applicationto run while the Application I-oaderwaits
for the me.hanicaldevicesto respondto l/O requests.

2.4.2.1Exampleol Asynchronous
Calls
Let'slookat a b.iefexample
showing
howyourapplication
canuseasynchronous
calls.
yourapplication
Suppose
mustloada programstoredon disk. The application
issues
the
A$LOAD systemcallto havethe Loaderloadtheprograminto memory,Let'st.acethe
actron one step at a trne,

Your application
issues
theA$LOAD systemcall. (Asynchronous
callsrequirethat
yourapplication
specirya response
mailboxfor communication
with theconcurrent
part of the systemcall.)

part of theA$LOAD callbeginsto run. Thispart checksthe
The sequential
parameters
for validity.

If the operatingsystemdetectsa problem,it placesa sequential
exception
codein
the word to which your except$ptr parameter points. It then returns control to your

application.It doesnot makethe Loadertask ready.
4.

Your applicationreceivescontrol. Its behaviorat this point d€pendson th€
conditioncoderetumed by the sequentialpart ofthe systemcalÌ. Therefore,the
applicationteststhe sequentìalconditioncodc. lf thc codc is E$OK, thc app[cation
continuesrunninguntil it mustusethe programloadedfrom the disk. At this point
your epplicationcan take advantageof the asynchronous
and concurrentbehavior
of the Loader. For example,your applicationcan usethis opportunityto perform
computations.
Ifyour applicationfinds that the sequentialconditioncodeis other than E$OK, the
applicationcsn assumethat the Loader did not make readya task to perform the
function.
For lhe balanceof this example,you can assumethat the sequentialpart ofthe
systemcall returnedan E$OK sequentialconditioncode.

Beforeyour applicationcan usethe loadedprogram,it must verify that the
concurrentpart of the A$LOAD systemcall ran successfuÌly.
The applicationissues
a RECEIVE$MESSAGEsystemcall to checkthe responsemailboxthat the
applicationspecifiedwhen it invokedthe A$LOAD systemcall.

When the result segmentis received,and successful
loadingis indicated,your
applicationcan use RQ$CREATE$TASK(usingthe entry point, data segment,and
stacksegment,specifiedin the result segment)to activatethe loadedprogram.

When the loadedprogramis no longerrequired,your applicationcrn deleteall the
segmentsthat were qeated for this programby the Application Loader,usingthe

ApplicationLoaderUsels Guide

2-5

APPLICATIONI,OADERSYSTEMCALLS

itself
segment
list in the endofthe Inader ResultSegment,
thenthe.esultsegment
canbedeleted.
2.4.2,2 GeneralitlesConcerningAgynchrgnousCallg
Theforegoingexampleuseda specificsystemcall(A$LOAD)to showhowasynchronous
with loadingoperations.Nowlet'slook at
callsallowyourapplication
to run concurrently
somegeneralities
aboutall iRMX II asfrchronous
calls.
.

andone
All ofthe asynchronous
systemcallsconsistof twoparts-oneseqùential
part onlyif the sequential
part runs
concurrent.The Loaderactivates
theconcurrent
(returnsE$OK).
successfully

Everyasynchronous
systemc; l requiresthatyourapplicalion
designate
a rcsponsc
with theconcurrent
part ofthe systemcall.
mailboxlor communication

wheneverthe sequential
part of an asynchronous
systemcalÌreturnsa conditioncode
otherthanE$OK,yourapplication
shouldnot attemptto receivea message
from the
response
existsbecause
theApplicationLoadercannotrun the
mailbox.No message
pa o[ thesystemcal]
concurrent

wheneverthe sequential
part ofan asynchronous
systemcallreturnsE$OK your
application
cancounton the Loaderrunningtheconcurrent
pa.t ofthe systemcall.
Your application
cantakeadvantage
ofthe concurrency
by doingsomeprocessing
beforereceiving
themessage
from theresponse
mailbox.

Whenever
part of a systemcallruns,the Loadersignalsits completion
the concurrent
by sendingan objectto theresponse
mailbox.Theprecisenatureofthe object
depends
on whichsystemcallyourapplication
invoked.You canfind out whatkind of
objectcomesbackfrom a particularsystemcallbylookingup thecallin fheExtended
|RMX ApplicatíonLoaderSystemCalk Reîerehce
Mahual.

The Loaderreturnsa segment
to yourapplication's
response
mailbox.Yoùr
application
mustdeletethe segment
whenit is no longerneeded.TheI-oaderuses
memoryfor suchsegments,
soifyour application
failsto deletethesegment,
it might
run shortolmemory.

2.4.3Response
MailboxParameter
Whenever
youissueanApplicationLoaderSystemcall(exceptto RQ$OVERI-AY),a
response
mailboxparameteris specified.Thismailboxhastwo differentfunctions,
depending
on the systemcallused.
For RQ(E)$S$LOAD$IO$JOB
thismaitboxse.vesto receivethe exitmessage
from the
loadedI/O job. Thisexitmessage
is sentby the ErlendedI/O Systemto thismailbox,
whentheloadedprogramterminates
by issuingthe RQ$EXIT$IO$JOB
systemcall. For
jobs
moredetailson I/O
andhowtheyterminatereferto therÍer dcdiRÌt/lxII E\lended
I/O $'stemUser'sGuíde.

2-6

Applicationtîader Usey'sGuide

APPLICATION
LOADERSYSTEM
CALLS

When an asynchronous
systemcall is invoked(A$LOADA$LOAD$IO$JOB,
RQE$A$LOAD$IO$JOB)this mailboxservesto allow the Loader to notify the callerthat
the concurrentpart of the syst€n call ìs finished. The l,oader sendsa r€suhscgm€ntto
this mailboxon completionofthe loadingprocess.
In general,the l-oader ResultSegmentiÌrdicatesthe result of the loadingoperation. The
fo.mat of a Loader ResultSegmentdependsupon which systemcall wasinvoked,details
on Loader ResultSegmentsare includedin descriptionsof the A$LOAD and
A$LOAD$IO$JOB systemcalls in the drlerded íRMX II Applícation Loadcr SystemCalls
ReferenceManual,
Ifyou usean AsynchronousI/O job systemcal (e.g.,RQ(E)$A$LOAD$lO$JOB),the
samemailboxreceivesthe Loader ResultSegmentaswell as the exit messagefrom the
newlycreatedI/Ojob. Thereîore,you canwait at the salre Írailbox two tirrcs, first for
the result segmentand then for the exit message,
exactlyin this order.
Avoid trsingthe sameresponsemailboxfor more than one concurrentinvocationof
asynchronous
systemcallsbecausethe ApplicationLoader may return Loader Result
Segmentsin an order differentthan the order of invocation.On the other hand,it is safe
to use the samemailboxfor multiple invocationsof asynchronous
systemcallsif the
followingconditionsare met:
.

One task invokesthe calls

The task alwaysobtainsthe resultof one call via RECEIVE$MESSAGEbefore
makingthe next cal

ApDlication
LoaderUsey'sGuide

ÀPPLICATION LOADER SYSTEM CALLS

2.5 EXAMPLE
$title

('exnp:

exaùrple of using the Applicatton

Loader')
*

/*-_**:l*,k*****************************************************************

*
*

ABSTRACT: This rnodule is an exarnple using tùo Application Loader
syslen calls - - RQE$A$LoAD$
Io$JoB and RQE$s gl,oAD$lo$JoB .

*
*

ìf ***********************************************************************/

exfìp : D0;
DECI-ARETOKENLITEMLLY
/*

]NCLUDES

SELECTOR.

$ ínctude (common.lit)
: inc: loader. ext)
$include
includè
: ínc: eios .ext)
$
: inc:nucfus. ext)
9include
STRUCTURES

/", Loadet ResulÈ Segnent returned by rqe$a$load$io$job */
DECIéRE ALOAD$RES$SÎRUC
I,ITERALLY' STRUCTURE(
r:eturnscode
ITORD,
excep$code
tloRD,
j obqtoken
TOKEN,
nsg9ren
EYTE,
section$count
WORD,
error$sec$typ
BYTE,
undef$refs
i,foRD,
nen$requested
WoRD,
nengrecelved
WoRD)' ;
/*

Exic nessagc sent by EIos on behalf

oî ai 1/o job chat calls

rqgexir9iogjob

DECI,ARE
EXIT$MSG$STRUC
(
L]TERALLY'STRUCTURE
return$code
LtORD,
excep$code
woRD,
j ob$token
TOREN,

msg$1en
nss (89)

BYIE) ' ;

,/* Excepcion handler

2-tl

structurè

Application t oader Usefs Guide

APPLICATIONLOADERSYSTEMCALLS

DECIARE EXCEP$HANDLERgSTRUC
LITERALLY'STRUCÎURE (
proc$pir
POINTER,
node
BYIE)' ;
/*

LTTEMLS

DECIARE
NOSTIME$LIM]T
UNLIMITED
NO9DE1AY
DET"AY$REQ
E$OK
TERMINATION9OK
F]FO
/*

VARIABLES

LITEMLLY ' OFFFFH,,
LITEMLLY 'OIFFFFH' ,
LITERALLY 'O' ,
LITERALLY '2' ,
LITERALLY 'O' ,
LITERALLY'OIOOH'
LITERALLY 'O';
*/

DECIARE
(conn, aload9mbox, sload$mbox, aloadgjob, sload$job)
(aloadqr€sSt, exit$seggr)
ToKEN,
(poot9nln, pool$nex)
DlroRD,
prio
BYTE,
(status, job$flags,
rask9flags) woRD;
DECL\RE
aroad$resgsèg
BÀSEDaload$fes9r ALOAT$RES
I STRUC
,
exit$nsg
BASEDexir$seg$È EXIT$MSG$STRUC,
èxcepqhandler
EXCEP9HANDLER9STRUC;

roKEN,

/***************,t***************rv**x****rt**************rt*x***x*x*x*****)r
* lnitíalize
exception handler stlucture and create naílboxes
* calls to lhe AppÌication Loader
*****:t*************:t*******5t+************************:t*****************/

excepShandler.pr.oc$ptr : NIL;
excep9handler. node - 0;
aload$!ìbox : rq$createqnailbox (FIFo, lQstarus) ;
l F s t a t u s o E $ O KT F E NG O T Oe x i r ;
sload$mbox - rqqcreate$mailbox (FIFO, @sratus) ;
I F s L a t u s o E $ O KT H E NC O T Oe x i r ;

ApDlication
liader Use s Cuide

for

!\"7o*
*

APPLICATIÒ\J LOADER SYSTEl,| CALLS

/*********************************
+ Now caÌt rqe$a$load9ioSiob. First, obÈatn a connection to the file,
* then prepare the input parameters.
Let the ApplicaÈion Loader decide
* hor larCe a pool the job wirr hawe. l{hatever decision the Application
* Loader makes, it r.,i11 not a1lov the new job to borrow nemory fron
* its parenr, i.e.,
\r1tl set max equal !o its ùìin. The loaded code will
* slart
executlon
it ts in roemory and l'i1l have the naxirntlll
*

nri^ri

lt<

*
*
*
*
*
*

h,rAhr

****:r***********rr**********************
conn - rq$s$attach$file(rA(7,'ny pros'),@status)
I F s l a L u s o E 5 0 K T H E NG O T Oe x i t ;

;

poor$nin, poolSnax - 0;
prio : 0;
job$fl,es:0;
task$f1ags - No$DE1,AY;
aload$job - rqe9a$load$io$job (conn, pool$nin, poolgnax, Gexcepqhandrer,
job$flags, prio, task$f1ags, aloadgmbox, Gsrarus);
-F
s t € È u 6 < > E $ O KT H E \ C O T Oc x i r ;

/:l*:9*************ìl*:l***:!*************************:t***************)k*)r*)r*)r**
* Since rqeqagload$io$job is asynchronous, at this poinr, only
:! ils sequential part is executed and loadinA is sri1l il progress.
't Prepare the paraneters foÈ rqe$s$1oad$io$job and call ir. Again
:! leÈ the Appllcation Loader decíde how targe a pool !o allocare,
* but now the job will have unlinited'cr€dir'ar
rhe parenr's pool.
'r In thls case oe vant executlon of lhe code to be under our control,
* i.e.,
delayed. It ls nosc likely chac now r\,,roApplÍcation Loader
* systen calls will load the sane file concurrenÈly.

*
:v
*
*

**************************ìt*******************************:!*************)t

pool9max = UNLIMITED;
Èask$frags = DEIAY$REQ;
a l o a d $ j o b : r q e $ s $ r o a d $ i o $ j o b ( @ ( 7 , , n yp r o g , ) , p o o l g n i n , p o o l g n a : .
@ è x c e p s h a n d r è r ,j o b $ f I a g s , p r i o , r a s k g f t a s s , s l o a d g n b o x , G s t a r u s ) ; r E s t a b ù s
a ESOKTHENCoTO exiti

/*)Y:l**************************:l:t*************)t*******************)t*)t******

:! At rhis poinr, ír is knom char rqe$s$loadgiogjob finished
* its vork, although, nothing ís ye! known about rqegagloadglogjob.
* So we Íait at the specified mailbox.

**********************:!*********)t*:t*:t*:!*******)t***:t******:!*:!****:t***:t****/

è1oad$res$r - rq$rece ive9message( aload$nbox , NogTIì'IESLTMTT,
NtL, (asrarus );
status o E90K THENc0T0 exit;

2-|l)

ApplicationLoaderUsels Guide

r].

APPLICATIONLOADERSYSTEMCALLS

/**************************:l*************************rl***********ìl******)t*
* At this point
Èhe Loadèr Result Setmenl can be inspected
to detèrnine
* lhe merÌory pool size allocated
to Èhe job, or if an error
* occurred,
see lts nature etc.
*****************:t****************
*******+*******:l*:r****/
IF aload$les$seg.return$code

*
*

T E R Ì , I I N A T I O N $ o KT H E N G o T o e x i t ;

/***********,1*******************************************************)k*****

*
*
*
*

It is now known that rqe$a$load9io$job conpleted successfull-y, and
the loaded prograrn is already waíting to get hold of lhe CPù slnce
no delay vas requested. The second copy of the progran is rairinS in
menory for pernission to start, so let ir start.

*****************************+**********************)t*)t******)t****'L***-**;L/

C A L Lr q g s t a r t $ i o 9 j o b ( s l o a d $ j o b , G s t a t u s ) ;

/*******************************)r.*
* The two loaded prograns are on and running, fírst l,ai! for then to
* terminate (issue an rq$exitgio$job call), then kill
them.
****)t*****************************
**************-t*-**-**/

e x i t S s e g $ t : r q $ r e c e i v e $ n e s s a g e( a l o a d q n b o x , N O $ T I M E 9 L I M I îN
, IL, !6sEaEus);
l F s t a t u s o E S O KT H E NC O T Oe x i '
/*

Here we can examine the exit nassage... */

CALL rqsdeleteqj ob (aload9job, @status);
I E s L a l u s o E S O KT H E NC O T Oe x i l
exic$seggÈ : !q$recelveSrnessage(sload$Íìbox, N09TIME$LIMIT, NIL , (3sralus);
'IF
s l a l u s o E 9 0 K T H E NC 0 T 0 e x i L
CALL r:q$deleteSj ob (sload$job, GsÈarus);
T F s t a t u s o E S o KT H E NG O T Oe x i c
exit:
C A L Lr q 9 e x l c 9 l o S J o b ( 0 , N I L , @ s l a t u s ) ;
TF scatus o E9OKTHEN
CAUSESINTERRUPT(3);

\,le ate in big trouble...

/**********************************
x The encl, if an error vas detected in lhÍs nodule, recovery can be
* attenpled, sornelhing can be printed to the terminal oì. che progranì
* can j ust terninate.
******************************************:!**********:l*:l********:l*******/

END exmp;

Application toader User'sGuide

2-ll

The ExtendediRMX II ApplicationLoader is à configurablelayer of the operating
system.The iRMX II OperatingSystemenablesyou to confÌgurethe type of load
function required by your system.Your systemmay be configuredfor a loadjob, which
includesall the Application Loader systemcalls,or for load,which includesonly the
A$LOAD systerncall. If you chooseall Application Loader systemcalls.the EIOS will be
incorporatedinto your systemby the ICU.
You can configurethe Application Loader read bulTersizeto optimizeloadingtime by
increasingor decreasilgthe amountof memoryusedby this buffer. That is, a smaller
buffer sizemay causea longerload time.
FinaIIy,you can configurethe minimum memorypool size. This valueis usedby the
Application Loaderwhile creatingan I/O job for newlyloadedprograms. lf you speci$
zero in the pool minimum parameter,the Application Loaclercomputesthe reqùired size.
For more information see the Extenrl.edíRMX II Interuct e Confígurutíon Utility Reference
Manual.

Application l-oader User's Cuide

A.1 OVERVIEW
TheExtendedjRMX II Applicationlnader usestwo kindsofconditioncodesto inform
yourtasksof anyproblemsthatoccurduringtheexecution
ola systemcall--sequenîial
conditioncodesandconcurrent
conditioncodes.The difference
betweenthe two kindsof
codesirvolvcsthc rnethodtheApplicationLoaderusesto returnthe codeto thecanng
task.
The meaningof a specificconditioncodedepends
on the systemcallthat returnsthe
code.For thisreason,thisappendirdoesnot list interpretations.
Relerto theExtended
|RMX II ApplicatiokLoaderSlsîemCatlrRefererc?manualfor an interpretationof the
cocles,
providesthenumericvalue
Thisappendix
associated
with eachconditioncodethe
ApplicationLoadercanreturn.To usetheconditioncodevaluesin a symbolicmanner,
youcanusethecodevalueslntel supplies
youcan
in the file ERROR.LIT.Alternatively,
assign (using dre PL/M-286 LITERAILY

slalcmenl) a mcanin8ful ramc to each code,

The following three sectionscorrelate the name ofa condition code with the value

returnedby theApplicationLoader.Onesectionliststhe normalconditioncode,onelìsts
exception
codesindicatinga programming
error,andonelistsexception
codesresulting
from environmental
conditions.No distìnction
is drawnbetweensequential
and
concurrent
eroasbecause
mostofthe codescanbe returnedaseither.
Thesesections
coveronlytheconditioncodesreturnedby thesystemcallsofthe
ApplicationLoader.Additionalconditioncodescanbeproducedby otherlayersthatare
usedby theApplicationLoaderwhileloadingthefile. For example,
if a mistakeis made
in the pathname
of theloadfile,youwill getan E$FNEXISTcrror corJeissuedby the I/O
system.A completelist of exceptioncodescanbe found in the eÍerdcd |RMX II Nucleus
User'sGuid".

Applicationt-oaderUse/s Guide

A-l

CONDITIONCODES

CODES
A.2 NORMAL
CONDITION
NAME OP CONDITION

HEXADECIMAL VALUE

E$OK

A.3 PROGRAMMER
ERROR
CODES
NAME OF CONDITION
E$JOB$PARM

HEXADECIMAL VALUE
8060H

A.4 ENVIRONMENTAL
CONDITION
CODES
NAME OF CONDITION
E$NOT$CONFIGURED
E$BAD$HEADER
E$EOF
E$NO$LOADER$MEM
E$NO$START
E$]OB$SIZE
E$OVERLAY
E$LOADER$SUPPORT

A-2

HEXADECIMAL VALUE
08H
62H
65H
67If
6CH
6DH
6EH
6FH

Applicationlrader User'sGuide

80286translatoro. assembler1-2

A
A$LOAD 2-3
advantages
of usingthe ApplicationLoader 1-1
Application Ioader
three categoriesof systemcalls 2-1
Application Irader features
configurabiJity 1 2
deviceindependence1-2
supportofprogramswith overlays 1-2
s)mchronous
and asynchronous
systemcalls 1-2
Application Inader features l-2
asynchronous
calls,factsabout 2-6
asynchronous
systemcalls 2-4

B
BND286
dynamicmem
option 1-4
segsize
control 1-4

c
COMPACTinterfacelibrary 1-3
COMPACTmodelof segmentation
1-3
conditioncodes
eflv onmentalA-2
normalA-2
pfogrammererrorsA-2
conditioncodcsA-1

ApplicationLoaderUseis Cuide

Index-l

INDEX (continued)

E
ERROR.LIT A-I
example
BIND 1-3
hovrto produccan SingleTask l-oadable(STL) file 1-3
exampleofasynchronouscalls 2-5
EXIT$IO$JOB systemcall 2-3

F
lèaturesof theApplicationLoader l-2

G
GDT slots 1-3

H
Human Interface(HI) DEBUG command l-3

I
I/O job cals
A$LOAD$IO$JOB 2-2
RQE$LOAD$IO$JOB 2-2
S$LOAD$IO$JOB 2.2
I/O job cals 2-1

L
Loaderconfiguration
paramefer2-2
Loaderresultsegment2-5
LocalDescriptorTable(LDT) 1-3
LODFIX records1-3

M
memorypooÌ sizefor a newjob 2-2

N
non-I/Ojobcalls2-1,3
non-I/Ojobcalls
A$LOAD 2.3

Index-2

Applicationtoader User'sGuide

INDEX lcontinued)

o
OVL286 (the 80286overlaygenerator) 2-4

P
pool$max2-2
pool$maxinputparameter2-2
pooumininputparameter2-2
preparingcodefor loadingbytheApplicationlnader 1-2

R
RCONFIGURE2-2
RECEIVE$MESSAGE
systemcall 2-5
RESP$MBOX
parameter2-3
response
mailboxparameter2-6
RMXFC.LIB 1-3
RQ(E)$LOAD$IO$JOB
2.3
RQE$LOAD$IO$JOB
2-2

s
S$OVERI-AY,description2-4
sequential
and€oncurrent
partsof asynchronous
calls2-4
SMALL modelof segmentation
1-2
stacksizesrequiredfor eachlayer 1-4
START$IO$JOB2-3
synchronous
andasynchronous
calìs2-3
synchronoùs
systerncalls
RQE$S$LOAD$IO$JOB
2.3
S$LOAD$IO$JOB
2-3
S$OVERLAY 1-3

T
TASI$FLAGSinputparameter2-3
The difference
betweenRQ$andRQE$systemcalls 2-1

U
useof LI'IERAILY

to give a nameto conditioncodes A-1

Applicstion I-r)aderUsefs Guide

Iridex-3

irÌtel'
E X T E N D Ei R
DM X " I I
U D IU S E R G
' SU I D E

intelCorporation
3065Bowers
Avenue
SantaClara,Californa 95051

! 1988,ntelCorporation,
Copyriqht
Alì RiqhtsReserved

Thismanualdescribes
Intel'sUniversalDevelopment
Intedaceasit appliesto the
Extended
iRMX@ll OperatingSystem.Themanualincludesa briefintroductionto the
UDI andits relationship
to theiRMX II OperatingSystem.

UDI Usefs Guide

lll

CONTE

CHAPTEB1

PAGE

CHAPTER
2
UDISYSTEMCALLSINAN iRMX@
II ENVIRONMENT

PAGE

CHAPTER
3,
UDIEXAMPLE

PAGE

APPENDIX
A,

PAGE

APPENDIX
B

PAGE

UDI Uset's Guide

CONTENTSlconfinued)

Figure1-1.The Application-Software-Hardware
Model.-.-.-.-.-.-.-.-..........-...-...................
1-I
F i g u r e2 - 1 .C h r o n o l o g y o f S y s t e m C a 1 1 s . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

UDI Usels Gùide

1.1 oVERV|EW
Intel'sUnive.salDevelopment
lnterface(UDI) is a setofsystemcallscompatible
with
severaloi lntel'soperatingsystems.
programmakesonlyUDI system
If an application
callswith no explicitcallsto an individualIntel operatingsystem,
the application
canbe
transported
betweenoperatingsystems.
Figure1-1illusuatesthe relationship
between
application
code,theprocessing
hardware,
andthelayersofsoftwarethatlìe between.

Applicalion
Codein IntelApplicaìion
Language(s)

Run.Time
Libraries
For
Non.malhematical
Feaiures
80287
U0l Libraries

of
80387
Support
Library

Operating
System

80286or 80386

f l7a8 I

Figurel-1. TheApplication-Software-Hardware
Model

UDI Use/s Guide

l-l

INTROIìLICTTON TO THE IINIVTRSAI, IìEVEI,OPMNNT INTERF'ACE

1.2 EXAMPLE
In Figure1-1,the downward
arrowsrepresent
commandflowanddataflowfrom the
applicalion
wherethecommands
areultlnatelyexecuted.
codcdown!o thehardv"are,
(Not shownin thefigureis anothersetof arrowsshowingtheupwardflowofdatafrom
the hardware to the application code.) Note that one ofthe downward arrows is crossed

out,signifying
thatthe application
codedoesnot makedirectcallsto the operating
system.Rathe.. all inte.actionhetw€enthe epplicationcodeand the operatingsystemis
done throughthe UDI software.
the UDI serveas the link betweenan applicationand the operatingsystem,yoù can
switchoperatingsystemssimplyby changingthe interfacebetweenthe UDI and the
operatingsystem.In other words,all you needto make an applicationtransportable
behveenoperatingsystemenvironmefitsis a UDI lìbrary for eachoperatingsystem.This
library alwayspresentsthe sameinterfaceto ùe application,but its interfacewith the
operatingsystemis designedspecificallyand exclusively
for that operatingsystem.Intel
providesUDI librariesfor thc iRMX 86, cxtandcdiRMX II, ScricsIII, and ScricsIV
operatingsystems.
The UDI systemcalls,while presentinga standardinterfaceto userprograms,behave
somewhatdifferentlywhen usedin different operatingsystemenvironments.This is
becauseeachoperatingsystemhasmanyuniquecharacteristics,
and someof them are
reflectedin the resultsofthe UDI calls.
The next chapterdiscusses
the UDI in the contextof the ExtendediRMX II Operating
SYstem.

UDI Uset'sGuide

2.1 oVERV|EW
This chapterdescribesthe reqùirementsandbehaviorof UDI systemcallsin the
bxtendediRMX It lI envtonment.

2.2 OVERVIEWOF
UDISYSTEM
CALLS
Thissectiondiscusses
the functìons
ofmanyUDI systemcals,highÌighting
the
interrelationships,
if any,amongcallsin variousfunctionalgoups.

2.2.1 MemoryManagementSystsmCalls
Whenthe iRMX II OperatingSystem
loadsand.unsa program,theprogramis allocated
memory,in an amountthatdepends
on howtheprogramwasconfigured.The portionof
memorynot occupied
byloadedmde anddata-thefreespacepool-isavailable
to the
programdynamically,
thatis,whiletheprogramruns.The operatingsystemmanages
memoryassegments
thatprograms
canobtain,use,andreturn.
Programs
canusetheUDI systemcallsnamedDQ$ALLOCATEand$MALLOCATEto
getmemorysegments
fronìthe pool. Theycanusethe systern
callsDQ$FREEanrl
DQ$MFREEto returnsegments
to thepool. TheycanalsocallDQ$GET$SIZEand
DQ$GET$MSIZEto receiveinformationaboutallocated
memorysesnents.

NOTE
The systemcallsDQ$MALLOCATE,DQ$MFREE,and
DQ$GET$MSIZEaresupported
onlyfor programs
compiledir the
COMPACTor I-ARGEsegmcntation
modcls.
The SMALL modelof segmentation
doesnot supportthe longpointers
usedby thesecallsto identifytheallocated
memory.

UDI User'sGuide

UDI SYSTEMCALLS IN AN iRM)€ II EÀI\4RONMENT

You canreservememoryfor theExtended
iRMX lI I/O Systemby usingthe systemcall
DQ$RESER\/E$IO$MEMORY
andby declaring
themaximumnumberoîbuflersand
filesto be attachedat anyonetime. Thisactionensures
thatthe operatingsystem
allocaressufficientmemoryto accommodate
anyI/O bulfer neededro op€na file. (The
I/O Systemcreatesbuffersfor everyfile it opens.)
DQ$RESERVE$IO$MEMORY
is usefulfor an application
programthathasusedall of
its available
memorypoolandwantsto opena temporary
file to storethe data. Ifthe
application
programhasnot previously
invokedDQ$RESERVE$IO$MEMORY,
the
operatingsystemreturnsan E$MEM exception
codewhentheprogfamtriesto createthe
temporaryfile.
TheE$MEM exception
conditionoccursbecause
theoperatingsystemrequiresmemory
job to openandaccess
job does
ftom the application
thespecified
file. If the application
not hav€anyavailable
memory,the operatingsystemcanno!openor access
morefiles.
Bùt il the application
programhascalledDQ$RESER!'E$IO$MEMORY
previously,
the
operatingsystemcanusethe memoryreserved
by thk systcmcallto manipulate
thefile.

SEEK
IRUNCAIE

DELEIE

Figùre2-1. Chmnolos/of SystemCalls

UDI Uset'sGuide

UDI SYSTEMCALLSIN AN iRMXOII EI.{IIRONMENT

2.2.2 File-Handling
SystemCalls
Aboutone-halfof the UDI systemcallsareusedto manipulate
files. Figure2-1 showsthe
chronological
relationships
aúongthemostfrequentlyusedfile-handling
systemcalls.
The keyto usingExtended
iRMX Il filesis themnnection.A programwantingto usea
file first obtains(a tokenfor')a conne.tionto thelile andthenusesthe connection
to
performoperations
on the file. Otherprograms
cansimultaneously
havetheirown
connections
to the samefile. Eachprograúhavinga connection
to a file usesits
connection
asifit hadexclusive
access
to the file.
A programobtainsa connectionby callingDQ$ATTACH (iI thc filc alrcadyexists)or
DQ$CREATE(to createa newfile). Whentheprogramno longer[eedstheconnection,
it can call DQ$DETACH to delete the connection. To delete both the connection and the

file. the programcalls DQ$DELETE.
Once a programhasa connection,it can call DQ$OPEN to preparethe connectionfor
input/output ope.ations. The programperformsinput or output operationsby calling
DQ$READ and DQ$WRITE. It can move the file oointer associated
with the connecuon
by caling DQ$SEEK.lt can rruncarerhe file by callingDQ$TRUNCATE.
When the prog am hasfinìsheddoing input and output to the file, it can closethe
mnncction by callingDQ$CLOSE. Note that the programopensand closesthe
connection,not the file. Unlessthe programdeletesthe connection,by calling
DQ$DETACH, it can continueto open and closethe connectionas necessary
If a progam callsDQ$DELETE to deletea file, the file cannotbe deletedwhile other
connectionsand I/O requestsattachedto the file exist. In that case,the file is markedfor
deletionand is not actuallydeleteduntil the last of the connectionsis deleted. During the
time that it is markedfor deletion,no new connectionsor I/O requeststo the file may be
$sued,

2.2.3 ProgramControlCalls
UDI providestwo sysîemcallsfor programcontrol:DQ$EXITandDQ$OVERLAY.
DQ$EXITterminates
a program,closingall openfilesandfreeingall allocatedresources.
You shouldalwaysincludethissystemcallasthelaststatemen!
in yourprogram.
DQ$OVERI,AYletsyoutakeadvantage
ofthe overlaysupportprovidedbythe operating
system.Thissystemcallloadsan overlayinto memory.Theoverlaymusthavebeen
preparedbythe BND286binderandtheOVL286overlaygenerator.

UDI Uset'sGuide

UDI SYSTEM CALLS IN AN iRMX@ II ENITRONMENT

2.2.4 UtilityandCommand-Parsing
Calls
parsingandfor operations
suchasdateandtime
UDI providessystemcallsfor command
stampingandsystcmidentification.Thesystemca s ar€DQ$CET$TIME,
DQ$GEI$SYSTEM$ID,
DQ$GET$ARGUMENT,
and
DQ$DECODE$TIME,
DQ$SWITCH$BUFFER.
DQ$GET$TiMEandDO$DECODE$TIME
retu.ndateandtime informationas
maintained
by the operatingsystem.Bothsystemcallsprovidethe samekindsof
information,
is a moregeneralsystemcallthatshouldbe used
but DQ$DECODE$TIME
possible.
insteadof DQ$GET$TIMEwhenever
DQ$GEfiSYSTEM$IDretumsa stringrhatidentifiesthe nameof the operaring
syslem.
programs
perform
Thissystemcallis usefulfor those
thatneedto
operating-systemspecilicfunctions.
enîbleprograms
to retrieve
DQ$GET$ARGUMENT
andDQ$SWITCH$BUFFER
pnrameters
from thecommand
line (or from anyotherprogrambuffer).
parsesthecommand
DQ$GET$ARGUMENT
line,returningthe nextparameterin the
sequence.
You caninvokeit several
timesto retrieveall theparameters
enteredwith a
command.DQ$SWITCH$BUFFER
switches
to a newbuffersothatthe nexttimeyou
callDQ$GET$ARGUMENT,
youwill retrievea parameter
from the newbuifer.

2.2.5ConditionCodesAnd Exception-Handling
Calls
Every UDI call exceptDQ$EXIT retuhs a numericconditioncodespecifyingthe result
of the call. Each conditioncodehasa uniquemnemonicnameby which it is known. For
example,the code 0, indicatingthat there were no enors or unusualcondìtions,has the
nameE$OK. Aly other conditionmeansthere wasa problem. Thesemndìtronsare
calledexceptions.
Exceptionalcóndjtionsare classifiedas follows:
.

EnvironmentalConditions. Theseare generallycausedby conditionsoutsidethe
control ofa program;for example,deviceerrors,incorr€ctfile refererìces,
ot
insufficientmemory.

ProgrammerErrors. Theseare typicallycausedby mistakesin programming.
Progmmmererrors can be subdividedinto hardwareerrors and errors in
programming.Hardwareerrors can includesuchconditionsas Divide-by-Zeaoerror,
Overflowerror, GeneralProtectionerror, er.ors detectedby the 80287Numeric
ProcessorExtension(hereafterreferredto genericallyas the NPX), aùd others.
Errors in programmingcan consistofconditions suchas incorrectparametert)?e,
invalid buffer. and others.

UDIUsedscuide

UDI SYSTEMCALLSIN AN iRM)@ II ENITRONMENT

If the SystemDebuggeris configuredinto the applicationsystem,all hardwareerrols will
causethe systemto breakto the monitor.Thisenables
the userto investigate
the faulty
codeusingthecapabilities
of the iSDM 286monitorandtheSystemDebugger.The
breakto themonitorwill occurregardless
of theexception
handlerandexception
mode
thatarein effectat thetimeofthe exception.Ifthe SystemDebugger
is not presentin
the application
system,
UDl handles
hardwareeÍo.sjust like otherprogÉmmererrors.
Thereù a .outinein theUDI interfacelibrarycalledRQ$ERRORthathandlesUDI
exceptions.This routine is calledwheneveran exceptioncodeis generatedby a UDI
systemcall. RQ$ERRORperformsthefollowingoperations:
.

If an environmental
conditionoccurs,theexception
codeis returnedto thecalling
program,whichcanhandletheconditionin-line.

If a programmer
erroroccurs,RQ$ERRORinvokestheNucleussystemcall
SIGNAL$EXCEPTION.
The actionthatSIGNAIJEXCEPTIONtakesdepends
on
the configurationofthe Nucleus(in particular,the settingof the EM parameterofthe
Nucleusscreenin the InteractiveConfigurationUtility). The EM (exceptionmode)
parameterdetermineswhen to transfercontrol to an exceptionhandler. If the
exceptionmode is NEVER (the default)or ENVIRON, SIGNAIJEXCEPTTON
passescontrol back to the callingprogramso that it can processthe exceptional
conditionin-line. If the exceptionmode is AIL or PROGRAM,
SIGNAI-$EXCEPTIONpassescontrol to the exceptionhandlerthat is in effectat lhe
time the exceptionoccurs.

You can overridethe actionsof RQ$ERROR by providingyour own RQ$ERROR
routine and bindingit to your programs.To overridethe defaultroutine,your routine
must containa PUBLIC proccdurcnamcd RQ$ERROR, and you must bind th€ routine
to you. applicationcodebelbre bindingthe UDI interfacelibrary. That is, in the BND286
command,the nameofthe file containingyour RQ$ERROR roùtine mùst appearbefore
the nameof the interfacelibrary. This causesyour RQ$ERROR routine to be bound
first, in placeof defaultroutine in the interfacelibrary. Your RQ$ERROR routine must
adhereto the modelofsegmentation(SMALL, COMPACT, or I-ARGE) usedin the
applicationprogam itself.
The sourcecodeof the defaultUDI RQ$ERROR routine is availablein the
/RMX286/UDI directory. You can usethis sourcecode as an examplewhen building
your own RQ$ERROR routine. The file UCERR.A28 appÌiesto SMALL and
COMPACT applications.ULERR.A28 appliesto LARGE applications.

UDI Usefs Guide

UDT SYSTEM CALLS IN AN iRMX@ II ENVIRONMENT

As explained
earlier,whenthe RQ$ERRORprocedure
invokesSIGNAII$EXCEPTION,
controlcanpassto an excepfion
handler.If the defaultsystemexception
handler
(DEF.EXCEPTIONHANDLER)
is in effect,it displays
theappropriate
error message
at
theconsoleandterminates
theprogam. Yourprogramcanestablish
its ownexception
handlerby callingDQ$TRAP$EXCEPTION.This exceptionhandlerwill be called
whenever
RQ$SIGNAUEXCEPTION
is invoked,in thedefaulrsystemthisis on
programme.
e.ror. DQ$DECODE$EXCEPTION
returnsa mnemonicdescription
of any
conditioncodegenerated
by a UDI system
call. The restof thissectionprovides
info.mationthatyouneedto writeyourownexception
handler.
After an exception
conditionoccursandbeforeyou. exception
handlergainscontrol,the
ErtendediRMX Il OperatingSystemdoesthefollowing:
1.

Pushes
theconditioncodeontothe stackof theprogramthatmadethe systemcall
generating
the exception
code.

Pushes
the numberof theparameter
thatcausedthe exception
ontothe stack(1 for
the first param€ter,2 for the second,etc.).

Pushesa WORD onto the stack(reservedfor future use).

Pushesa WORD fo. the NPX onto the stack.

Initiates a long call to the exceptionhandler.

Ifthe conditionwas not causedby an erroneousparameter,the .esponsibleparameter
numberis zero. If the exceptioncodeis E$NDP$ERROR,the fourth item pushedonto
the stackis the NPX statusword, and the NPX exceptionshavebeencleared.
Programscompiledunder the SMALL model of segmentationcannothavean alternate
exceptionhandlerbecausealternateexceptionhandlersmusthavea LONG POINTER,
which is not availablein the SMALL model. Therefore,progams compiledunder the
SMALL model must ùse the defaulrsystemexceptionhandler.
UDI alsoprovidesa methodfor programsto handleany CONTROL-C charactersthat
are t'?ed while the programis running. The defaultCOMROL-C handlerterminates
the programthat wasactivewhen the CONTROL-C wasentered However,a program
can overridethe defaulthandlerfor the durationofits executiooby calling
DQ$TRAP$CC and supplyinga long pointe. to the new CONTROL-C handler. The
operatingsystemwill call this new CONTROL-C handlerwhenevera CONTROL-C is
g?ed at the terminal. The new handlerremainsin effect until the programcalls
DQ$EXIT, or until it establishes
anotherhandlerby catlingDQ$TRAP$CC again.

2-6

UDIUset'sGuide

UDI SYSTEMCALLSIN AN iRMX@II EITURONMENT

2.3 MAKINGUDICALLSFROMPLIM-286ANDASM286
PROGRAMS
This section describeshow to make UDI calls ftom a program, using the
DQ$ALLOCATE systemcaìl as an example. lhe information from this examplewill
enableyou to make the other UDI calls. T\vo examplesare presented:one for a call from
a PL/M-286 programand one for a call from an ASM286program
This chapter showsthe DQ$AILOCATE

systemcall $'ntaj{ as follows:

sègStoken - DQSALI,oCATE
(size, excepr$ptÌ);
The examplethat followsrequests128bytesofmemory. It expectsa token for the l2Eb)'te segmentin ARRÀY BASE and a conditioncodein ERR.

2.3.1 ExamplePL/M-286CallingSequence
DECIARE

ARRAYBASE
ERR

TOKEN,
WORD;

ARRAYBASE- DQSALLOCATE
(128, @ERR);

2.3.2 ExampleASM286CallingSequence
MOV
PUSH
LEA
PUSH
PUSH
CALI
l,lov

AX,128
AX
AX, ERR
DS
AX
DOALINCATE
ARRAYBASE.
AX

; firs!

paraúeter

; second paraneter
;
: rerurned

value

Thisexampleis applicable
to programs
thatexfrectto usethe COMPACTandI-ARGE
interfaceto UDI. For the SMALL interface,
omitpLNhing
theDS segment
register.

2.4 WritingPortableProgramsUsingThe UDI
Not all programsmakingIIDT callswill be portableacrossall UDI-supportedoperating
systems.However,you can employthe followingprogrammingtechniquesto ensurethat
the programsyou write are portable(or as portableas possible):
.

Never examinefilenames(and pathnames)in your program. The rulesfor forming
pathnamesare operating-system-dependent.

UDI Uset'scuide

IIDI SYSTEM CAI,I,S IN ÀN |RMX@ II NNVIRONMENT

2-8

Modiry f enamestringsonly by callingthe UDI procedure
DQ$CIIANGE$EXTENSION.

Wo.k only with pathnamessuppliedby the user,pathnamescreatedby calling
DQ$CHANGE$EXTENSION,or predefinedfilenames.

Alwayscheckthe exceptioncodeto seeifa call failed.

youshouldcreatethe necessary
Whenhandlingerrorconditions,
file connections
rn
the inítialpart of progamsor makea DQ$RESERVEÍIO$MEMORY
callbeiore
makinganyothe. UDI systemcall.

UDI Usefs Guide

3.1 oVERV|EW
Thischapterpresents
an exampleoi UDI systemcalls.FollowingtheprogramÌistingis
the SUBMITfile thatwasusedto createthe executable
module.

3.2 EXAMPLELISTING
$conpact
9optimize ( 3)

/*************************************************************)t****)t***)r*
*
* Protian UPPER

* This progran denonstrates the use of UDI file-handling
and
* comand-line-parsing
sys.èn calls.
The progran reads an input
* file of characters and converÈs all lowercase alphabetic characters
* to uppercase. The converted data are wrltten to a second file
* UPPERexpects

lhe coruìand line

[To outfile]

UPPERinfíle

that

* (If "T0 outflle" is nor specified,
**********************************

fnvokes

1t to be of the forù!:

:C0: is assuned.)
*********************/

upper: D0;
DECI-ARE
CR
LF
TOKEN
BOOLEAN

E$oK
ESFATAL9EXIT
lrritè$only

UDI Usefs Guid€

LITEMLLY
LITERALLY
LITERALLY
LITERALLY
LITEMLLY
I,ITER-AJ,LY
LlTERALLY
LIÎERALLY

,ODH'
,
, OATI
,SELECTOR'
,
"
,BYTE'
,

' 0 ',
, 3 ,,
' 2 ',

3.1

T]IìI EXAMPLE

false
tIUE
co$conn

LITEMLLY '0' ,
LITERA]-LY'OFÍ.H';
TOKEN;

9include (/rnx286lincludi . ext)
t íon' )
9subtitle ( ' check$excep
/)k********************************

*
'r

P.ocedure to cÌreck aù excepcio& code. If LlLe excepl-lon code is
not EgOK, print a nessage and exlc.
******************************************************/

(exceptlon,
check$exception:
PROCEDIIRE
lnfo$p)
DECL1RE
exception
WORD,
ínfóSp
PoINTER,
info
BASED info9p STRUCîI,RE(
COUNT BYTE,
char(1) BYTE),
exc$buf STRUCTURE(
COUNT

REENTRAÌfl;

BYTE,

char(80)
BYîE),
I oca l$excep WoRD:
IF exceptÍon o E90K THEN
DO;
CALI, dqSdecode$exception (exception, @exc$buf, GIocal$excep);
cALl dq$wríte (co$conn, Qexc$buf . char, exc$buf . count, @1ocal$excep);
cALl-dq$write (coqconn, @(': '), 2, Glocal$excep);
CALL dqgwrite (cogconn, Ginfo.char, info.count,
@localgexcep);
CALL dq$vríte (co9conn, @(cR, 1,F), 2, Grocal$excep);
cALl, dq$e>.it (ESFATAL$EXIT);
END;
END check$except ion;
9subtlÈle('ì,faÍn')
/***********:!************************************************************

ìf

---

--MArN PROCR_AÌ{

**********************:!************************************************)t/

DECI.ARE
single$buffer
double$buffer
status

LITERALLY / 0' ,
LITERALLY'2',
WORD;

DECI.ARE
tn$na!oe(5O)
outgnane(50)
in9conn
out9conn

BYTE,
BYTE.
ToREN,
TOKEN,

UDI Use/s Guide

UDI EXAMPLE

BYTE;

deI iÌn
DECI,ARD
buffer( 1024)
lnScount
i.
not$done

HoRD,
I.IORD,
BOOLEAN;

cogconn- dq$cre,lte (@(4, ';co:'),
CALL dq$operi (coqconn, wrtte9only,

Gstatús);
stngleqbuffer,

Gstatus);

/*********************************
*
Ignore the Daoe of the plogra$ (clìe flrsc artuent)
******************:l***************
***************rt***/

delln * dq$get$arsunent (@buffer, @status);
CALL check9excepcion ( scatus, NIL);
IF delin ' CR THEN
CA.LI-dq$èrit (ESo():
*******************+
/*********************************
*
Attach the inpuc fiLe, and open ir.
**********************************
**,r****************/

delin = dq$get$argurnent (lQin$nane, @status) ;
CALL check9exception (status, NIL) ;
in$conn - dqsattach (@in$nane, Gstatus);
CALL check9exceprion (status, Ginqnane) ;
C A L Ld q S o p e n( i n $ c o n n , r e a d $ o n l y , d o u b l e s b u f f e r . G s t a t u s ) i
CALI- check$excepÈion (status, @in$name);

/*********************************
*
Find out if there is an outpút filè specified.
Tf so, attach
*
and open lt.
If not, use :C0: for outpuc.
*****************
*,r*****************/

CR THEN

deliro - dq$gec$argì.nent(@buffer, @status);
CALLcheck$exception (status, NIL) ;

UDI Usefs Guide

UDI EXAMPLE

(deliro - CR) 0R
(buffer(O) o 2) oR
'T') oR
(buffer(1) c
(buffer(2) o 'o')
THEN
DO:
CALL dq$\.'ri!e (co$conn, @('Invalíd
LF), 21, Gstatus) ;
CALT dq$exlC (E$FATAL$EXIT)
;
END;
IF

output file',

CR,

deltn - dqqget$argunenr (Gour$narne,@sratus) ;
CALL checkqexception (status, NIL) ;
, s!atus) i
o u t g c o n n - d q $ c r e a t e ( G o u r S n a m eG
cAlL check$excepÈion (status, eout$nane) ;
CArL dqgopen (outgconn, vrite$only,
2, Gstatus);
C A L L c h e c k s e x c e p ti o n ( s r a t u s . @ o u t s n a m e ) :
END;
ELSE
out$conn = co$conn;

Write Èo :CO: if

/;":!******)rr*,1**************************:t***:r****************************
*
Read fron
input,
converL,
a d vrire
**************:k**************************************)r*,t****,r*********//

no fíIe

specified

oucpur

no!$done = true;
D0 trrÌìILEnot$done;
inScount - dqgrer.t lins..nn. (ahufrèr, sizè(buffer),
@status);
CALL check$exceptíon (status, @in$nane):
lF inqcount - 0 THEN
notsdone - fa13è;
IF notsdone THEN
D0;

,/* If no characrers are in the,
//* fiIe, rhen f6i1 nexÈ rest.

*/
*/

/* If characLers ale ln the */
,/* fÍle, then process them. */

DO t=0 TO Ín$count-l;
IF (buffer(t) >:'a')
A N D( b u f f e r ( i ) < - ' 2 , )
THENbuffer( i) - buffer(i)
END;
cALÌ, dq$lrrlEe (out$conn, ebuffer, ingcounc, !6slacus) ;
CALI, check$exception (status, Gout$narne);
END;
END;

3-4

UDI Useis Cuide

UDI EXAMPLE

/*********************************************************************
*
close inF[t and outpuÈ files,
snd ertt
*********************************************************************/

CALI- dqqclose (tn$conn, €status) ;
CALL chcck$cxccption (st€Èus, @ingnde) ;
CALL dq$close (out$conn, @srarus) ;
CALL check9exception (status, @out$nane):
cAr,L dq$exic (E$OK);
END upper;

3,3 COMPILINGAND BINDINGTHEEXAMPLE
Thc programUPPER wascompiledand boundon an exrendediRMX Il-basedsysrem
usingthe followingcommands:
pln286 upper.p28
bnd286 upper. obj , &
: l a n g :p Ì n 2 8 6 . l l b , & < C R >
/rn.x296/líb /\d rifc . l ib rc(dn(1000H,2000H))&
ss (stack(2000H)) object(upper)
Thesecommandscan be entereddirectlyat the terminal,or placedin a file with a .CSD
extensionand invokedby usingthe SUBMIT command.

3.4 UDI INTERFACE
LIBRARIES
The interfacelibrariesfor theUDI are
UDIIFS.LIB SMALL model
UDIIFC.LIB COMPACTmodel
UDIIFL.LIB IARGE model

UDI Uset'sGuide

3-5

The followingdatatypesarerecognized
by the iRMX 28óOperatìngSysrem.
BYTE

An ùnsigned,
eight-bitbilary number.

WORD

An unsigned.
rwo-BYTE.
binarynumber.

INTEGER

A signed,
two-BYTE,binarynumber.Negativenumbersarestored
in two's-complement
fom.

POINTER

Twoconsecutive
WORDscontaining
thebaseselectorof a (64Kbyteprocessor)
segment
andan offsetinto the segmont.The offset
is in thewordhavingtheloweraddress.

SELECTOR

An indexinto a descriptor
tablethatidentifiesa particularmemory
segment.Thedescriptor
table€ntryliststhesegment's
base,its
limit,its t)pe,andjts privilegelevel.

TOKEN

A SELECTORthatidentifiesan object.A tokenmustbe declared
literaly a SELECIOR.

DWORD

A 4-BYTEunsigned
binarynumber.

BOOLEAN

A BYTE thatis considered
to havea valueofTRUE ifir is oFFH,
andFALSEif it is 00H. A booleanmustbc dcclarcdliterallya
BYTE.

UDI Usefs Guide

Thisappendix
liststheconditioncodenngesgenerated
by eachlayerof theExtended
iRMX II OperatingSystem.Exception
codesareclassified
aseither',Environmental
Conditions"
or "Programmer
Errors,rrThelatterclassification
includescertainhardware
efforsaswellasprogaamming
errors.
Thevaluesof theseconditioncodesfall into rangesbasedon the Efended iRMX II layer
thatfùst detectsthecondition.TableB-1liststhelayersandtheir ranges(in
hexadecimal).
Thetableshowsthelayer(s)thatcouldgcncratethecode,in caseyouwish
to referto theappropriate
manual.
TableB-1. ConditioriCodeRanses
Leyer

Environmerìtal

Prcgramming

Nucleus

1Hto 1FH

8000Hto 801FH

l/O Syrems

20Hto 5FH

8020Hto 805FH

60Hto 7FH

€060Hto €07FH

8OHto AFH

8O8OH
to SOAFH

UniversalD6v6lopm€nt

to DFH
C,OH

io SOOFH
SOCOH

Rgssrvedlor Int6l

EOHto 3FFFH

SOEOH
to BFFFH

4MOHIo TFFFH

to FFFFH

'lhe

Operutor'sGuíde to îhe |RMX II Hut eh Inteface glvesthe val]ueof each code and its
associatedmnemonic,aswell as a short descriptionofits significance.

UDI UsePscuide

B-1

80287Numeric ProcessorExtension2-4

A
Application-software-hardware
model 1-1

B
BN'D2862-3

c
Closingconnections
2-3
Conditioncodes2-4
ConditioncodesB-1

D
DatatypesA-1
Deletionof a file 2-3
Divideby Zero error 2-4
DQ$ALLOCATE2-I, 7
DQ$ATTACHsystemcau 2-3
DQ$CLOSEsystemcall 2-3
DQ$CREATEsystemcall 2-3
DQ$DECODE$EXCEPTION
systerh
call 2-6
DQ$DECODE$TIMEsystemcall 2-4
DQ$DELETEsystemcall 2-3
DQ$DETACHsystemcall 2-3
DQ$EXITsystemcall 2-3,4, 6
DQ$FREEsystemcall 2-1
DQ$GET$ARGUMENT
systemcall 2-4
DQ$GET$SIZEsystemcall 2-1
DQ$GET$SYSTEM$ID
systemcall 2-4
DQ$GET$TIMEsystemcall 2-4
DQ$MALLOCATEsysteftcall 2-1
DQ$OPENsystemcall 2-3
DQ$O\€RI-AY systemcall 2-3
DQ$READsystemcall 2-3
DQ$RESERVE$IO$MEMORY
systemcall 2-2,8
DQ$SEEKsystemcall 2-3

UDI User'sGùide

Index-l

Indexlcontinued)

DQ$SWITCH$BUFFER
system
call 24
DQ$TRAP$EXCEPTION systemcall 2-6
DQ$TRUNCATE systemcall 2-3
DQ$WRITE systemcal 2-3

E
Environmental
Conditions2-4
Exampìe
ASM286callingsequence2-7
BIN'D 3.5
PL/M-286 callingsequenc€2-7
Exception
codesB-1
handling 2-4

F
Filedeletion2-3
File-handlingsystemcalls 2-3
Freespacepool 2-1

G
GeneralProtectioneÍor 2-4
Guidelines
for writingportableprograms2-7

I
InteractiveConfigurationUtility 0CU) 2-5
Interfacelibrariesfor the UDI 3-5
ISDM monitor 2-5

M
MakingUDI callsfrom PL/M-286andASM2862-7
Memorymanagement
2-1
Memorymanagement
systemcalls 2-l

N
NPX 2.4

o
Openingconnections2-3

Index.2

UDI User'sGuide

INDEX(continued)

Operatingsystemactionsafteran eror occurs2-ó
Operatingsystems,switching 1-2
Overflowerror 2-4

P
Programcontrol systemcalls 2-3
Programportabfity 2-7
Programmer
errors 2-4

R
Reservingmemory 2-2
RQ$ERROR2.5

s
Seeking2-3
Segments
2-l
SIGNAII$EXCEmON systemc.all2-5
Switching
operatingsystems1-2
Systemcalls
exception
handling2-4
file-handling2-3
memorymanagemenr
2-1
prograúcontroÌ2-3
utilityandcommand-parsing
2-4
Systemdebugger2-5

T
Temporaryfile 2-2
Transporting
code 1-2
T)?esof data A-l

U
Utility and command-parsing2-4

UDI UsefsGuide

Index-3

intet
EXTENDEDIRMX@II
DEVICEDRIVERS
U S E R 'G
SU I D E

Int€l Corporation
3065BowersAvenue
5anîaClara,Californta
95051
o 1988,lntelCorporation.
Copyriqhî
All RiqhrsReserved

PREFACE
The I/O Systemis the part ofthe ExtendediRMX lI OperatingSysîemthat enables
accessto files on peripherzrldevices.(The term "I/O System"encompasses
both the Basic
I/O Systemand the ExtendedI/O System.)It is implementedas a set of file driversand
a set ofdevice drivers. A file driver providesuseraccessto a particulartype offile,
independentof the deviceon which th€ file resides.A devicedriver providesa standard
interfacebetweena pijrticular deviceand one or more file drivers. Thus,by addingdevice
drivers,your applicationsystemcan supportadditionaltypesof devices.It can do this
without changingthe userinterface,becausethe driversremain unchanged.
This manualdescribesthe differ€nt lypesof devicedriverssupportedby the I/O System
(common,randomaccess,terminal,and custom). It illustratesthe basicconceptsofthese
drivers,and it describeshow to write your own driversot'thesetypes. In addition,it
discusses
eachof the Intel-supplieddevicedriversand providesany specialinformation
neededto usethosedrivers.

ReaderLevel
To use the Intel-supplìeddevicedrivers,this manualassumes
you are îamiliar with these
Itemsl
. The PL/M-286 programminglanguageand/or the ASM2fì6Macro Assembly
l,anguage.
. The ExtendediRMX II OperotingSystemand the conceptsof operatingsystem
tasks.segmenîs.
andotherohjects.
. The I/O System,as describedin lhe Eúended íRMX II Basic I/o Slstent User's
Guirle and the Extended|RMX II futended I/O Sytem User'sGuide. These manuals
documentthe userinterfaceto the I/O Sy'stem.
. The configurationprocess,as describedinthe Ertended|RMX II InteracÍive
Confíguntion Utilit Rekrence manr?L
This manualassumesthat ifyou are writing your o*n devicedriversyou are a systemslevelprogrammerexperiencedin dealingwith I/O devices.ln particular,it assumesthat
you are alsofamiliar with the following:
. The hardwarecodesnecessary
tÒperform actualread and write operafons on
your I/O rJevice.This manualdoesnot documenlthesedevice-dcpcndent
instructions.
.

Regions,as described ir't the Extended|RMX II Nucleu,sUset'sGuide.

Devic€DriY€6 User'sGuide

lll

PREF,TCE

Convenlions
Wheneverthis manualdescribesI/o operations,it assumesthat tasksuseBasicI/O
Systemcalls(suchas RQ$A$READ, RQ$A$WRI]E, and RQ$A$SPECIAL). Even
thoughnot mentioned,the taskscan alsousethe equivalentExtendedI/O Systemcalls
(suchas RQ$S$READ,RQ$S$WRITE,and RQ$S$SPECIAL)or UDI cals (DQ$READ
or DQ$WzuTE) to perform the sameoperations.

DeviceDriversUser'$Guide

CHAPTERI
INTRODUCTION

PAGE

CHAPTER2

PAGE

DeviceDriversUser'sGuide

CONTENTS

CHAPTER
2 (conrinued)

PAGE

18
,..,.,...........22.3.4.2
Terminal
Modes........,..........................
2.3.4.3
UsinganAuto-Answcr
Modemwitha Terminal...............................,,..2-44
2-48
abouta Terminal................................................
2.3.4.4
Obtaining
Information
to
connectión....
....................2-49
2.3.4.5Restricting
theUseof a Terminal One
InsertingDatainto a Terminal'sInputStream...-.2-50
2.3.4.óProgrammatically

CHAPTER3

PAGE

CTIAPTER4

PAGE

DeviceDriversUseÌ'sGuide

CONTENTS

CHAPTER5
WRITINGCOMMONOR RANDOMACCESSDEVICEDRIVERS

PAGE

CHAPTER6
WFITINGIERMINALDRIVERS

PAGE

DeviceDriveróUser'sCuide

vll

CONTENTS

CHAPTER
6 (conlinued)

PAGE

CHAPTER
7
WRITINGA CUSTOMDRIVER

PAGE

CHAPTER8
HANDLINGUO REOUESTS

PAGE

vlll

DeviceDrirers UsefsGuide

CONTENTS

CHAPTER9

PAGE

APPENDIX
A

PAGE

APPENDIXC
SUPPORIINGTHESTANDARDDISKETTEFORMAT

PAGE

APPENDIX
D
INTERPRETING
BADTRACKINFORMATION

PAGE

DeviceDriversUseÌ'sGuide

CONTENTS

TABLE

PAGE

FIGURES
FIGURE

PAGE

DeviceDriversUsels Cuide

CONTENTS

FIGUBE(continued)

PAGE

9-5 UDS DeviceInformationScreenfor Interruotless
Terminalf)evices. . . . ....S.11
9-6 UDSDeviceInformation
Screen
for Random
Ac.essDevice..
...................,...,...,.,9-12
9-7 UDS DeviceInforúationScreenfor MULTIBUS@
II Message-Passing
Random
Access
Devìce.,...................................
..,.,.,,,,,.,.,,,,.,.,.9-12
9-8 UDSDeviceInfo.mation
Sc.een
for General
Device..............................................
9-13
g-g UDS Unit InformationScreenfor TerminalDevice...............,.....,..........................
9 14
9-10 UDS Unit InformationScreen{or RandomAccessDevice.........,.,.,.,.,.,......,.,.....914
9-11UDSUnit Information
Screen
for General
Device..........................................,.,...915
9-12 UDS Device-UnitInformationScreenfor T€rminalDevice................................9-15
9-13 UDS Device-UnitIrformationScreenfor RandomAccess
Device....................9-16
9 14 UDS Device-UnitInformationSoeenfor GeneralDevice..................................9-1ó
9-15Example
UserDevices
Screen
..,............
..,...,.,.....................9-25
9-16 ComputingDeviceandDevice-UrÌit
NumbersandBND286Information.........9-28
9-16 Computing
DeviceandDevice-UnitNumb€rsandBND286Information.........9-29
9-17 PublicDeclarations
Neededfor theDINFO andUINFO Tables........................
9-31
9-18Portionof theMotiificdSUBMITFile
..............................9-32
A-1 RandomAccessDeviceDriverInitìalizeI/O Procedure
........................................
A-3
A-2 Random
Access
DeviceDriverFinishl/O Procedure..........................................,{-6
A-3 Random
Access
DeviceDriverQueueI/O Procedure....,.....,........,.,......................
A-8
A-4 Random
Access
DeviceDriverCancel
I/O Procedure..........................................A-1
A-5 Random
Access
DeviceDriverInterrupt
Task..............,.........,.,.............................
A- 12
B-1 Random
Access
DeviceDriverInitialize
I/O Procedure..........................................BB-2 Random
Access
DeviceDriverFinishI/O Procedure
..............................................8
5
B-3 Random
Access
DeviceDriverQueueI/O Procedure
.............................................B-7
B-4 Random
Access
DeviceDriverMessa{c
Task.............................-...........................
B-10
D-l FormatofBadTrackInformation
.....:
..................,........,.,..
D-3

DeviceDrivers lJser'sGuide

The I/O Systemis implementedas a set of file driversand a set of devicedrivers. FiÌe
driversprovidethe supportfor particulartypesof files (for example,the namedfile driver
providesthe supportfor namedfiles). Devicedriversprovidethe supportfor particular
devices(for example,a MassStorageControllerdevicedriver providesthe facilitiesthat
enableyou to usean iSBC 214 Multi-Peripheralcontrollerto control a rùinchester-q?e
drive, a flexiblediskettedrive, or a tape drivewith the l/O System).Each tlpe of file has
its own file driver, and eachdevicehasiN own devicedriver.
One of the reasonsthat the I/O Systemis broken up in this manneris to provide device,
independentI/O. Appìicationtaskscommunicatewith file drìvers,not with device
drivers. This allowstasksto manipulateall files in the samemanner,regardlessofthe
deviceson v,'hichthe files reside. File drivers,in turn, communicatewith devicedrivers,
which provide the instructionsnecessaryto manipulatephysicaldevices.
When an applicationtaskwantsto communicatewith an I/O device,it must connectthe
file driver it wantsto usewith the appropriatedevicedriver. This connectionoccursat
executiontime when the task invokeseither the BasicI/O Systemcall
A$PHYSICAL$ATTACH$DEVICE or the ExtendedI/O Systemcall
LOGICAL^$ATTACH$DEVICE. ln both of thesecalls,the task must specifowhich file
driver and which dcviccdriver are beingusedtogether. Oncethis devic€conn€€tronrs
established,
applicationtaskscan manipulatethe deviceaccordingto the file driver
assignedto it (named,physical,or stream),without concerningthemselvesabout device
specifics.The deviceconnectionestabljshedeariier enablesthe file driver to
communicatewith the devicedriver and handlethe devicespecificsautomatically.
Figure 1-1showsthe levelsof communicationand how tasksconnectfile driversand
devicedriversto establishdevice-independent
I/O.

DeviceDriversUsey'sGuide

t-l

INTRODUCTION

APPLICATION
TASK
:
RO$LOGICAL$ATIACH$DEVICE
o
l
d"v.!S$Igre .re$d ue'
Cat,

jlf Arl9H$91c1
Ro$PHYs'c

)

Inlerface
File-independent

Stream
F ]e Driver

FileDr ver

Named
FileDflver

nterlace
Drve-rndependenl

DeviceDriver

Devce Driver

DeviceDriver

Device

Dev ce

x-1784

Flgure 1-1, ConnectlngFile and DeviceDdverf

The I/O Systemprovidesa standardinterfacebetweenfile driversand devicedrivers. To
a file driver, a deviceis merelya standardblock of data in a table. To manipulatea
device,the file driver callsthe devicedriver procedureslsted in the table.To a device
driver, all file drìvers seem the sarne. Every file driver calls device drivers in the same
manner. This meansthat the deviced.iver doesnot needto mncern itselfwith the
conceptof a file driver. It seesitself as beingcalledby the I/O System,and it returns
informationto the I/O System.This standardinterfacehasthe followingadvantages:

t-2

The hardwareconfigurationcan changewithout extensivemodificationsto the
softwa.e. lnsteadof modiryingentire file driverswhenyou want to changedevices,
you needonly substitutea differentdevicedriver and modi$ the table.

The I/O Systemcan supporta greaterrangeofdevices. It can supportany device,as
Iong as you supplya dcvicedrivcr that interfacesto the file driversin the standard
manner.

DeviceDrivers Usefs Guide

INTRODUCTTON

1.1 t/O DEVTCES
ANDDEVTCE
DRTVERS
EachI/O deviceconsists
of a controllerandoneor moreunits.A deviceasa wholeis
identified by a uniquedevicenumber. Units are identified by unit nurnberandby deviceunit number-The devicenumberidentiîiesthecontrolleramongall thecontrollersin the
system,
the unit numberidentifiesthe unitwithinthe device,andthe uniquedevice-unit
numberidentifiestheunit amongall the unitsofall of thedevices.Figurel-2 containsa
simplifieddrawingof threeI/O devices
numbers.
andtheirdevice,unit,anddevice-unit
Theremustbe a devicedriver(eitheruser-written
or Intel-supplied)
for everydevicein
the hardwareconfiguration.That devicedriver musthandlethe I/O requestsfor all of
rhe ùnirsúe devicesupporrs.Diffe.ent devicescanusedifferent devicedrivers;or if rhey
arethesamekind ofdevice,theycansharethe samedevicedrivercode.(For example,
rwoiSBC214controllers
aretwoseparate
devices
andeachhasits owndevicedriver.
However,thesedevicedriverscansharecommoncode.)

Figure1.2. DeviceNumbering

DeYice
DriYersUsels Cuide

1-3

INTRODUCTION

DRIVERS
1.2 TYPESOFDEVICE
TheI/O Systemsupports
four tlpesof devicedrivers:custoú,common,randomaccess,
andrerminal. Thesefoú tlpes are disdnguishedby wheúer theyhavea dfuectinterface
to the I/O Systemor whethertheyhavean interfaceto Intel-supplied
supportcode.They
arealsodistinguished
bywhichsetof supportcodetheyuseasthe interfac€.Iìigure1-3
providesan overviewofthe interfaces,listing
theprocedures
thatthe devicedriversmust
supply.Theshadedportionsof thefigurerepresent
thecodethatthe usermustwritefor
eachg?e of devicedriver.
As Figure1-3shows,
thehìghest-level
interfacebetweentheI/O Systemandthe device
driverconsists
procedures
(known
aslnitializel/O, Finishl/O, QueueI/O, and
of four
CancelI/O) that theI/O System
calls.Customdriversmustsupplythesefour
procedures.
For random-access/common
driversandterminaldrivers,the OperatingSystemprovides
supportcodethatincludesthesehighlevelprocedures.
The supportcodefor eachtypeof
driverprovidesfeatures(suchasqueuingor baudratecontrol)neededby eachdriverof
thatt'?e. 'fo ftke advantAge
of thesefeatureswhenwritingrandom-access/common
driversandterminaldrivers,youneedto writeonlya setof lower-level
procedures
that
selveasthe interfacebetweenthehardwareandthe supportcode.Figurel-3 showsthese
pfocedures.
The lbllowingsections
providemoreinformationabouteachqpe of driveÍ.

'f .2.1 CustomDrivers
A customdevicedriveris oneyoucreaîein its entirety.Thisqpe of devicedrrvercan
assume
anyform andprovideanyfunctionsyouwish,aslongasthe I/O Systemcan
access
il bycallingfour procedures,
designated
as
InitializeI/o
Finish I/O
OueueI/O
CancelI/O
Chapter2 describes
the advantages
anddisadvantages
of witing a custoúdriver.
Chapter7 describes
the interfaceto whichthe user-written
procedures
mustadhere.

1-4

DeviceD versUsePsGuide

INTRODUCTION

B a s i €l / O S y s l e m

B an d o mA c c e g g
and
C o m m o nD f i v e r
SupponCode
Initializel/O
Finishl/O
Oueuel/O
Cancell/O

Terminal
Driver
S u p p o nC o d e
Initializel/O
F i n i s hl / O
Queuel/O
Cancell/O

Terminal
Driver

Device

Dev i c e

Device

Fieùre l-3. DeviceDriver Inferfaces

DeviceDriversUser'sGuide

r-5

INTRODUCTION

1.2.2 RandomAccessandCommonDrivers
The operating Systemsuppliessupportcodethat providesmuch ofthe highJevelcode
(but not the device-spe,cificcorJe)ncrcssary tor operatirlg devicesclassified as random
accessor common.
A commondeviceis a relativelysimpledevicesuchas a line printer (but not a termìnaÌ).
Devices classified as common devicesconform to the following conditions:
.

these
A îirst-in/first-out mechanismfor queuingrequestsis sufficientfor accessing
devices.

Only one interrupt level is neededto servicethe device.

Data either read or written by thesedevicesdoesnot needto be dividedinto blocks.

A randomaccessdeviceis one in which datacan be read from or written to any addressof
the device(a disk drive, for example).Devicesclassifiedas randomaccessdevices
conformto the followingconditions:
.

Or y one interrupt level is neededto servicethe device.

I/O requestsmust be dividedinto blocksof a specificlength.

The devicesupportsrandom accessseekoperations.

The OperatingSystemprovidesa singleset ofsupport codewith the basicroutines
neededby both commonand randomaccessdevices.Thesesupportroutinesprovide a
queuingmechanism,an interrupt handler,and other featuresneededby commonand
randomaccessdevices.Chapter2 givesmore informationaboutthesefeatures.

1-6

DeviceDriversUser'sGuide

INTRODUCTION

Ifyou arewritinga devicedrivcrfor a rlevicethatfits into eitherthecommonor random
youdon'tneedto writetheentiredriver.Instead,youcanwritejust
access
classifications,
the followingspe.cialized,
devicedependent
procedurcs
andsct up an intcrfaccbesecn
themandthesupportcodeprovidedby the OperatingSystem:
DeviceInitialize
DeviceFinish
DeviceStart
DeviceStop
DeviceInterrupt
Chapter5 describes
moreabouttheseprocedures.

1.2.3 TerminalDrivers
As with commonand randomaccessdevices,the I/O Systemprovidesthe highJevel
supportcodeneededto operateterminals.A terminal is classifiedas a devicethat reads
and writes singlecharactersor blocksofcharacters,with an interrupt for eachcharactef
or block of characterssent.
Thc lcaturesprovidedby the I/O System'sterminal supportcodc are describedi-n
Chapter2. If you are writing a driver for a deviceclassifiedas a terminal,you don't need
to write thc cntùc drivcr. Instcad,you can take advantageof the l/O System'stermmal
supportcodeby writingjust the followingdevice-speciiic
routines:
Tefminal Initialize
Terminal Finish
Terminal setup
Terminal Answer
Terminal Hangup
Terminal Check
Terminal Output
'lerminal
Utility
Chapter6 describesmore abouttheseprocedures.

1.3 r/O REQUESTS
To thedevicedriver,an I/O requestis a requestby the I/O Systemfor thedeviceto
performa certainfunction.Functions
supported
by theI/O Systemare

DeviceDriversUsefsGuide

TNTRODIICÍION

Name
Attachd€vica
Derachd€vicé
Op€n
Clos€
Read
Write
Seek
Special

Number
4
5
6
7
0
1
2
3

Description
Preparea d€vic6ior us€,
Disconnect
a devic€,
Preparethe
deviceor a l5leon th€d6vic€for l/O op6rations.
T6rminat6l/Oop€rations
onlhe dsvic€oron afrl€.
Readîrom ths d€viceat the curerìt location.
Wrheto thedevic€at th6cur6ntlocation,
Mov€roa newlocationon th€d€vice(randomaccessdevic€sonly).
Portomtunctions
thr epplyto some,blit notall,d€vic€s-fhe sp€cialtunctions
available
includ€:
Name

1-8

Derriorion

Format
Ìrack
Ou€ry
Satisty
Notit

G€{disk/
rap€dara

Get
torrninat
data

Obtatninformalion
aboulth€
cur€ntconfrguration
ofa
terminal(suchas parity,baudrate,schomod€,ancl
duplex).

Sel
lerminat
dai,a

Changethecurerìtclnfiguation
ofat6rminal.

S€tsignal

Designat€
a characl€r
that,whenlypedarthe
kelboard,ssndsa signaltothesystem.

R€wind

R€windatap€to itstoadpoint.

Readlape
lll€mark

Mov€rhetapototh€n6xtfit6
markonlhotapg.

Wito tap€
fi16mark

wlit€ a lll€ markat the curr6nt
positionon th€tap€.

0
I
2

Formatafack on a mass-storagg
devtq€,
aboutsùoam-file
requests.
Obtaininlormation
Artifcially
salist a streamfil€l/O requesr.
Request
notilicaiion
llfien a volumebecomes
unavailable.
Obiaininirmationabóut
Winchestsr
disk6(6ucheÉthsnumberoffix€dand
removable
crind66, th€ numbq of s€ctors,andthe
socrorsìz€)and
abodiapes(suchaswhetherthe
tapeis pres€ílandtho numb3rof ùacks).

DeviceDriversUset'sGuide

INTRODUCTION

Name

Numbe.

Descriprion

R6t6nsion
tap€

Fast-forward
thetapeto th€ end
andth€nrewìndthetap€to rtsloadpo nt.

Sdt bad
rúack/
seclorinfo

Writeth€ localons of bad tracks
of seclofsto a specialarea
of
ths volum€lhatsloresìhatlnlormatlon.

G€tbad
tfeck/
sectorinlo

Refievethe locatonsot bad
fack6 or s€clorsftomthe
intormation
atorédonlhe volume.
Funcfionnumbersin therange14through32,767
arefes€rved
by Inrelfoftutufeuse. Functìon
nu..bersin th€ Éngo32,768through65,535decima
mightalsódenotespecaltunctions.
lhese numbers
aroava ablefor user-specifìed
specal functions.

The l/O Sysîem makes an I/O request by sending to the device driver an I/O
request/result segnent (IORS) containing the necessaryinformation. (The IORS is
described in detail in Chapter 4.) Indicated in the IORS is th€ t)?e of op€ration that nlust

beperformed,the device,andotherimportantinformation.The devicedrivermust
translat€ this request into specific device commands to causethe device to perform the
requested operation (if the operation is valid for the requested device).

LleviceDrivers Ilserrs Guide

I-9

This chapterdescribesthe featur€savailablcwith th€ different tlpes of drivers. For
random access,
common,and terminal drivers,this chapterliststhe capabilitiesprovided
by the I/O System-supplied
supportcod€. For customdrivers,for which there rs no
suppof codeprovided,this chapterlists the advaritages
and disadvantages
of Miting a
múpÌete customdriver insteadof adheringto one ofthe other categoriesand usingthe
I/O System-supplied
supportcode.

2.1 CUSTOM
DRIVERS
The most basicdevicedriver interfaceis the custominterface. Wirh this interface.îhe
I/O Systemprovidesno assistance
for standardoperations(ior examplc,it docsn,t
automaticallyset up a queueto handledevicerequests).lnstead,the customdriver must
provide all the functionsneededto control the device.
Chapter7 describesthe progtam interfacebetweena customdriver and the I/O System.
The next few paragraphsdiscussadvantages
and disadvantages
ofwriting customdrivers.

2.1.1Advantages
of CustomDrivers
The most obviousadvantageofcustom driversis they enableyou to add supportfor
devicesthat don't fit into the common.randomaccess.
or teÍninal catecories.and for
which Intel doesn'talreadyprovitlea prewrittendriver. The customdriver irterface
enablesyou to add supportfor any deviceyou choose.
Another advantageofcustom dtiversis they are not restrictedto the limitationsimposed
by the other driver interfaces.For example,the randomaccesssupportcodesetsup a
queuingmechanismto handlerequestsfor the device. In this queu€,requestsare handled
in a way that minimjzesa disk'sseÈktime. lfyou want to handledevicerequestsbasedon
a priority basisinstead,you can write a customdriver to provide that feature.
In summary,the customdriver interlàceenablesyou to provide supportfor any device
and in anv mannervou choose.

I)eviceDrivers flser's Guide

FEATT'RES OF THE DRTVT:RI\TERFACFS

of CustomDrivers
2.1.2 Disadvantages
to writing customdriversrather than usingone of the
There are severaldisadvantages
other driver interfaces.
First, customdriversusuallytake lorger to write, becauseyou mustprovideyour o\ùfl
versionsof the standardfeaturesthat the I/O Systemalreadyprovidesfor common,
randomaccess,and terminaldevices.
Also, debuggingtime tendsto increasefor the samereason.r ith more codeto write,
there is a greaterchanceof errors occurring.
Finally,unlessyou coordinalelhe desÌgnofyour customdriversto allow codesharing,the
codesizeof customdriverstendsto be larger. with .andom accessdrivers,all driversuse
the samerandomaccesssupportcode. With mostcustomdrivers,eachdriver must
provide all of its own functions,therebyduplicatingthe functionsprovidedby other
clìstomdrivers.

2.2 RANDOMACCESSAND COMMONDRIVERS
The I/O Systempaovidessupportcodethat handlesmany of the standardfunc,tions
required by commonand randomaccessdevices.If you useone of the lntel-supplied
commonor randomaccessdrivers,or ifyou write your own driver and adhereto the
common/randomaccessmodel,your drivershaveaccessto all the capabilitiesof the l/O
System'ssupportcode.
The samesupportcodehandlesboth commonand random accessdevices,and the
interfaceto the supportcodeis the samefor both kinds of devices(as describedin
Chapter6). The I/O Systemdetermineswhethera deviceis a commondevice(lìke a line
printer) or a randomaccessdevice(like a disk drive) by a valueyou supplyin a table
(calÌeda device-unitinformationblock or DUIB) that describesthe deviceto the I/O
System.The DUIB is descrìbedin derailin Chapter4.
The valuethat distinguishes
commonfrom randomacccssdrivcrsis callcd
NUM$BUFFERS. A nonzerovaluefor NUM$BUFFERS indicatesthat the deviceis a
random accessdeviceand that the I/O Systemshouldusethat manybuffersofmemory to
perform data blockingand deblockingoperations.Theseblockingand deblocking
operationsare specialfeaturesofthe randomaccesssuppoatcodethat guaranteethat
read and write operationsstart on sectorboundaries.
A zero valuefor NUM$BUFFERS tells the I/O Systemthat the deviceis a common
deviceand that there is no needto worry aboutblockingand deblocking,or about any
o[her specialfealure associated
with aandomaccessdevices.

DeviceDriversUser'sGùid€

FEATUR.ES
OF THE DRIItsR INTERFACES

2,2.1 FeaturesCommonand RandomAccessDevicesCanAccess
Severalfcaturcaofthe supportcodeare availablero both conìmonand r-andouaci-css
devices.

2.2.1.1 lnterruptTasksand InterruptHandlers
For commonandrandomaccess
devices,
thesupportcodecreatesan interrupttaskand
an interrupthandlerto communicate
with the devices.Althoughthe use.-written
procedures
mustprovidethedevice-specific
code,the supportcodesetsup the structure
for the interrupttaskandthe interrupthandler.
The interruptlevelfor thehandlerandtaskis configurable.
You specifythelevelwhen
yousetup thedeviceinformationtable.Referto Chapter5 for moreinformation.
2.2.1.2ReouestOueue
The supportcodesetsup andmanages
a queuefor handlingdevicercquests.Whenever
î
taskrequests
access
to thedevice,the supportcodeplacestherequestin the queue.It
processes
requests
for commondevices
in a first-iÌr/fist-outmanner.It processes
requests
for randomaccess
devices
in a modifiedfirst-in/first-outmannerthatminimies
the device's
seektime (seethe "SeekOptimizatjon"
sectionlaterin thischapter).
2.2.1.3 VolumeChangeNotlfication
Oneof the optionsof theA$SPECIALandS$SPECIAL
a raskro be
rystemcallsenables
notifiedwhenever
thevolumeon a devicebecomes
(suchaswheoswappirg
unavailable
diskettes
or changing
tapecartridges).Thisfeaturerequiresthatthe deviceis capableof
detectingandsignalingvolume
changes
or thatthelowleveldevicedriverprocedures
can
recogniethechange.
Altcr the taskrequests
thisnotification,
thesupportcodesignals
the taskwlteDever
a
volumehasbeenchanged
(or whenthe stopbuttonhasbeenpressed).Thisallowsthe
task to detach the device arìd attach it again, so as not to coÍupt rhe data on a new

volumeby assumingthe previousvolumeis stillpresent.
If the deviceitselfcan recognizewhen a volumehasbeenchanged(or when the stop
button hasbeenpressed),all the user-writtendtiver codemust do is detectwhen a dooropen or other similar conditionoccursand call the I/O System-supplied
procedure
NOTIFY (describedin Chapter5). The supportcodehandlesthe rest.
Once the supportcodenotifiesan applicationtaskthat a volùme hasbeenchanged,the
applicationtask can dctachthc deviceand reattachit.

DeviceDriversUse/s Guide

2--ì

FEÀTURESOF THE DRTVERINTERFACES

2.2.1.4AttachbeforeAccess
If a task attemptsto perform an I/O operationon a commonor randomaccessdevice
beforeinvokingeither the PHYSICAL:$ATTACH$DEVICEor
LOGICAL$ATTACH$DEVICE systemcall,the supportcodere.ognizesthat the device
hasn'tbeen initialized. Insteadof attemptingto perform the operation,the supportcode
returnsan E$IO exceptioncodeto the invokingtask.

2.2.1.5 Long-TermOperations
(suchasrewindinga tape)takea considerable
SomeI/O operations
amountof time.
Insteadof delayingI/O operations
on all unitsof a devicewhilea long-termoperation
takesplace,the supportcodeprovidesa mechanism
that enables
driversto specilywhen
long-termoperations
startandwhentheyarecomplete.with thisinformation,
the
supportcodecanprocess
operations
on otherunitsofthe samedevicewhilethelong-term
operationis in progress.
For thismechanism
to work,the user-written
drivercodemustcallthe InteÌ-supplied
BEGIN$LONG$TERM$OP
procedures
andEND$LONG$TERM$OP
whenstartingand
finishinga long-termoperation.Chapter5 describes
theseprocedures
in detail.
Long-termoperations
on someunitsrequiremultjpleoperations.For example,
rewindifig
a tapemightrequireseparate
rewindandreadfile markoperations.The supportcode
providesa mechanism
thatenablesdriversto performmultipleoperations
before
notilyingthesupportcodethatthelong-termoperationis complete.To usethis
mechanism,
theuser-written
drivercodemustca[ theIntel-supplied
CET$IORS
procedure
eachtime it wantsto performanotherintermediate
ope.ation.Chapter5
describes
rhisCEfiIORS procedure.

2.2.2 SpecialFeaturesfor RandomAccessDevices
In addition to the features listed in the previous section, the I/O System'ssupport code

suppÌies
severalotherfeaturesthatapplyspeciiically
to randomaccess
devices.
2.2.2.1 Diyidingl/O Requestsby Sectoror by Track
As mentioned
earlier,therandomaccess
supportcodecandivide1/O requests
into
multiplerequests,
eachof whichreadsor writesinformationstartingat sectorboundades.
Thishappens
auiomatically,
wirhourspecialcodingin the user-written
procedures.
A similarfeatureenables
theI/O Systemto guarantee
thatno singleI/O requestcros3cs
a trackboundaryon devices
with uniformgranulariry.Duringdeviceconfiguration,
the
usercanchoosewhetherthesupportcodeprovidesthisfeature.Whenthisfeatureis
activated,
the supportcodespecifies
deviceaddresses
astracknumber/sectoa
number.
just
Otherwise
it specifies
them
with a logicalblocknumber.

2-4

DeviceDriversUser'sGuide

FEATURESOF THE DRIVERINTERFACES

2.2.2.2SeekOptimlzation
The randomaccesssupportcodeautomaticallyordersread,write, anrl scekrequesrsin a
way that minimizes overall device accesstime. For example,for disk drives, the requests
are orderedto minimizeheadmovement.This imorovesoerformanceofthe entire
system.

2.2.2.3 Seek Ovèrlap
Randomaccessdevicescanoverlapseekoperations(whichtake relativelylongperiodsof
time)on oneunit of a devicewith otheroperations
on otherunitsof thesamedevice.To
facilitate!his,thesupportcodecandividereadandwriteoperations
into separate
seek
operations
followedby reador writeoperations.Whilethe seekoperationis takingplace
or one unit, the support codc can start another operation on anotlter unit. For lhis to

workho.ùever,
theuser-written
d.ivercodemustcallthe Intel-supplied
SEEK$COMPLETE
procedure
whenthe seekoperationis finished.Chapter5 explains
theSEEK$COMPLETE
procedure
in moredetail.
2.2.2.4 Relries
lfan l/O operationlàilsbeaause
of a sitùationthatmightnot existeverytime the
operationis attempted(controllers
usuallycategorìze
theseassofterro.s),the .andom
access
supportcodedoesn'treturnan exception
codeimmediately.Instead,it retfiesthe
operationasmanytimesastheuserspecifies
duringconfiguration.
Thisprocess
is
automaticanddoesnot rcquirethe user-written
driverroutinesto includeanyspecial
code.All the driverroutinesmustdo is setthestatuscodeto E$IO (2BH)andtheunit
statuscodeto IO$SOFI 12)in theIORS.

2.3 TEBMINAL
DRIVERS
Ifyou useone of the Intel-suppliedterminaldrivers,or ifyou write your own driver and
adhereto the terminal driver model,you haveaccessto all of the capabilitiesofthe l/O
Systern'sTerminal SupportCode.
Thesecapabilitiesincludeusingcontrol charactersto control terminal I/O, redefining
thosecontrol characters,setttngconnectionand terminalmodes(includingsettingup
charactertranslationand simulation),usingan auto-answermodem,inquiring aboutthe
current terminal setup,limiting a terminal to one connection,and programmatically
insertingtext into the terminal'sinput stream.
The followingpa.agraphsdescribehow to usethe Terminal SupportCode to control a
terminal.

DeviceDriYersUset'sGuide

F'EATURESOF THE DRIVER INTERFACES

2.3.1Terminall/O
Therearethreebuffersinvolvedwhenever
a taskreadsinputfrom a terminal:the raw
input buffer, lhe Terminalsupport code input buffer, andthe applicadontask'sbuffer.
Eachterminaldevice-unit
hasits ownrawhput bufferandits ownTerminalSùpport
Codeinput buffer. Eachtaskthat readsinput from a terminal hasits ownbuffer. Fìgure
2-1showshowthesebùffersinteract.

rahenappri.aronrask

ren nal9uppofcode

Figure2-1. BùffersUsedin Terminal I/O

As Figure2-l shows,
inputcharacters
passthroughall threebulferson thei wayfrom the
terminalto the application
task.

2-6

First,theterminaldrivertakescharacte.s
from thedevice(the terminal)andplaces
theminto therawinputbuffer.

Whenthedevìcedriversignals
theTerminalSupportCodethatan inputinterrupt
hasoccurred.
theTerminalSupportCodetransfe.sthecharactenfrom the raw
inputbufferto theTerminalSupportCodeinputbuffer.

DeviceDriversUserrsGuide

FEATURES
OF THE DRIVERINTERFACES

Whenùe l/O System
passes
a teadrequesrto theTerminalSupportCode
(because
a taskcalledA$READor S$READ$MOVE
andspecified
a connection
to
a terminal),the TerminalSupportCodcmovesthecharacters
from its inputbuffer
to thetaskbufferfor thisreadrequest(thetaskspe.cified
a pointerto thisbuiferin
its,A.$READ
or S$READ$MOVE
call).

2.3.1.1RawInputBuffer
Thesizeof therawinputbufîer,andwherethebufferresides,
depends
on the q?e of
terminaldriver.For nonbuffered
(devices
terminaldevices
thatdo not havedual-porî
memoryof theirown),the terminaldrivermustcreatea logicalsegment
for the rawinput
bufferwhenit initializestheunit. For bufferedterminaldevices.
the rawinoutbuffer
residesin the dual-po.tmemoryof the terminalconrrollerboard.Referro ihe "Terminal
InitializationProcedr.rre"
seciionof Chaoter6 to seehowthe rawinDutbufferis
initialized.
Whenthe TerminalSupportCodetransfers
characters
ftom the rawinputbufferto its
inputbuffer,thenumberofcharacters
in therawinputbufferdepends
on the t,?e of
terminal device.
tsut1èred
terminaldevices
do not needto sendan interruDteachtime an inoutcharacter
is
transmitted,
sotheremightbe manychararrers
in lhe ra; inputbufferwhenaninput
inlerruptoccurs.Themaximumnumberdepends
on thesizeof thebuffereddevice's
inputbufferfor thatdevice.
Nonbuffered
devices
mustsendoneinteÍupt for eachinputcharacte.,
sothereis usually
oDlyonecharacterin therawinputbufferat a time. However,therawinputbuffer
enables
othe.inputcharacters
to be sentwhiletheTerminalSuppo.tCodeis processing
thepreviousinputcharacter.Fo. nonbuffered
devices,
thesizeofthe rawinputbuffer
providedby lntel-supplied
driversis 25óbytes.
2.3.1.2TerminalSupponCodeInputBuîfer
Thesìzeof theTerminalSupportCode'sinputbufferis fixEd.The bufferfor each
terminaldevice-unit
is 256decimalbyteslong. EachTerminalSupportCodeinputbuffer
is dividedinto twologicalbuffers:a qpe-ahead
bufferanda line editbuffer. How input
characters
movethroughtheselogicalbuffersandinto theapplication
task'sbuffer
depends
on theterminal'sinputmode.
If the terminal'sinputmodeis line-editmode,characters
ftst moveinto the type-ahead
buffer.Theymovefrom the t,?e-ahead
bufferto theline-editbufferwhenthe user
performsline-editing
functions(thecharacters
usedto perfo.mline-editing
functionsare
described
laterin the "Line-Editing
Functions"
sectionof thischapter).Whenthe
TerminalSupportCodereceives
a readrequestftom the I/O System,
it movesthelineeditedcharacters
to therequesting
application
task'sbuffer.

DeviceDriversUser'sCuide

FEATURES OF THE DRIVER INTERFACES

The maxirnum
numberofcharacters
thatan application
taskcanrequestof a terminalin
line-editmodeis 253decimal.(Thisallowsonecharacter
for a line terminator,usuallya
carriagereturnor a linefeed.) Ifthe terminaloperatortriesto typemorethan253
eachextla
characters
beforeq?ing a line terminator,theTerminalSupportCodediscards
characterandechoes
a bel (CONTROL-G)to the terminal.
or llushmode,theline-editbufferis not used.
If a terminal'sinpùtmodeis transparent
Characters
bùfferto theapplication
task'sbufferwithoutbeing
movefrom the9?e-ahead
line-edited.However,eventhoughthechamcters
aren'tline-edited,
theTerminal
SupportCodestill mightmodilysomeof thecharacters
beforeplacingtheminto the
application
task'sbuffer. Outputcontrolcharacters,
OSCsequences,
andTerminal
Character
Sequences
canall be intercepted
andmodifiedbytheTerminalSupportCode,
depending
on the termirial'scurrentconneation
modes.(kter se€tions
in thischapter
describe
thesecharacter
sequences
andtheconnection
enable
or disable
modesusedto
them.) lf youwantto ensurethatall qpesof characters
without
canbereceived
modification
whenthe terminalis in transparent
or flushmode,youmustalsosetthe
outputcontrolmodeandthe OSCcontrolmodesothattheTerminalSupportCodedoes
not acton thesecharacters
whentheyappearin the inputstream.
2,3.1,3 DifierencebetweenTransparentand FlushMode
Thedifference
betweentransparent
modeandflushmodeis howtheTerminalSupport
Codetreatsreadrequests.
In flushmode,the readrequestreturnsimmediately
with asmanycharacters
ascurrently
residein theTerminalSupportCode'sinputbuffer,up fo the numberofcharacteN
requested.Thismeansthatanynumbea
ofcharacters,
from 0 to the numberrequested,
mightmoveinto theapplication
task'sbuffer.
In transpare[tmode,thereadrequestdoesnot returnuntil all thecharacters
requested
by the application
taskaremovedinto theapplication
task'sbuffer.
The maximumnumberofcharacterc
thatcanbe readin onerequest,in eithertransparent
or flushmode,is 255for nonbuffered
devices
and255Dlusthesizeof the devjce's
dualpofi memoryfor buffeaeddevices.

CAUTION
In tmnsparentmode,ifany chamctelsbecome
lostduringtransmission,
an input rrqùestcanrcmainùnsatislied.In this case,theterminalwill
appearto benodfunctional.

2-8

DeviceDriversUsels Guide

FEATURXSOF THE DRIVERINTERtrACES

2.3.2 ControllingTerminall/O
TheTerminalSupportCodesupplies
a setof controlfùnctionsthet,whenplacedin the
inputstreamof data,affectthemannerin whichdataflowsbetweenthe BasicI/O System
anda terminal.Therearetwo kindsof controlfunctioris:line-editing
functionsand
outputfunctions.Thecontrolcharacters
assigned
to thesefunctionsareconfigurable
(referto the"ControlCharacter
Redefinition"
se.ction
ofthis chapter),but a defaultsetof
controlcharacte.s
is provided.Thenexttwosections
discuss
thesecontrolcharacters.
Not all the chaaacters
describedin the nexttwo sectionsîake effectwhenenteredfrom a
terminalrunningundertheHumanInterfaceCLI. Theonlycontrolfunctionsthatstill
opcratcundcrth€CLI arethedeletecharacter,
lineterminatorcharacter,
emptyq?eaheadbuffercharacte.,
startoutputchamcter,
andstopoutputchamcter.Referto the
Opemtor'sGuideto theErtcnded|RMXII Hunan lhteface for informationconcemingfhe
specialcharacters
that areavailable
with theCLl.
In thesetwo sections,
the term"cu.rentline"refe.sto the setofcharacters
(possibly
with
editinghavìngbeenperformedon them)thattheoperatorhasenteredsincethe most
recentlyenteredline terminator.
2.3.2.1LineEditingFunctions
Thc controlfunctionsthattheTerminalSupportCodeusesto editdatain the line-edit
bufferaredescribed
in thenextfewparagraphs,
alongwith the defaultcontrolcharacters
assigned
to performthosefunctions.Eachcontrolcharacter
described
herecanbe
replaced
with a differentcontrolcharacter
by meansofcontrolcharacter
redefinition,
whichis described
laterin thischapter.

NOTÉ,
The line-editing control characters deseribedin the following paragraphs
are effectiveonly when the terminal'smodeis line-edítmode (the default
rnode)and when the charactersappearin the input stream. The
charactershaveno effectwhen the terminalis in transoarentor flush
mode.or *hen the characters
appearin rheoutpur.trÀur.

I)eviceDriversUset'sCuide

2.9

f,.E,ÀTURESO[' THE DRT!'ER INTERF'ACES

Function
L ne
terrainator

Delete
charadsr

Deflult
Control
Characl€lsl

D€scriotion

Cariag6
R6tumor
Lin€F€€d

Î€rminat6sth6cur€ntlin6. Ent€ ng shhera cariag€roturnor a lineleedcalrses
tho T6rminalSupport
Cod€to inssda carriaqerstumanda lin€l6€dinlolhe
cur€ntlin€, Aft€rrcceiving
a lin€terminator,
th6fgrmìnalSupportCodemoveslhe
curentlin€(orth6numb€rol charact6rs
sp€cif6dintho inputrequ€st,ilth€ rèquesl
is for tew€rcharaclsrsthan are in ìha clrsrìr line)fromthe typsah€ad buffer,
throughlh€line€ditbuffer(iflin€-editing
mod€is in €ffsct),rorhstasldsbull€r.lf
characi€rs
romainin th€ lin+€dilbulf6r,th€T€rminal
SupponCod€useslhemto
satist thonexlroqu€r lcr inputlromthotormanal.

Rubout

R€mov6sth€ lastdatacharaclerftom th€ currentlins. That is, th€ rubout
proc€dingúeruboutcharacler
characî€r
andùe dalacharad€rimm€diat€ly
ln lhe
currentlinearebothr€movsdftomth€curont lin6. ll th€terminalhasa disolav
scrc€n,thechaactercombination
(backspac€)(spac€)(backspace)
is ochoedtothe
scr€€n.ll lhél€fminaloLfputis hardcopy,th6delet€dcharacter
is displayed
a
sscondtim6,suroundsdby '#' characters.
Forexample,
th€ saquenc€
'CAT(ruboú)(rubout)(rubout)'
$euldappearas CAT#TAC*andwouldenterand
aemov€
th€ l€ttersC, A, andI fromth6cur€ntlin€.

Ouot€nért
characl€r

CONIROL-P Causesthen€xtcharaci€r
€nt€r€dto b€ treatoda6data,€v€nìl thatcharacter
is normally
a linè€ditingcontfolcharaci€r.(Odpulcorììrolcharacl6rs,
suchas
perrormtheirnormaltunclions
CONTROL-S
andCONÍROL'Q,
6venif pr€csdedby
a CONTBOL-P.)
Duínglin6-édh
mode,theTerminalSupport
Coderemoves
the
CONTROL-Plrom
th€cur€ntlin€br,jtleavesthedisabledcharacterthat
followsin
th€ inputslrcam.Neith€rrhe
CONTROL,P
northecharacter
thatimmediately
followsn aredisDlaved
atth€t€rmrnat,

Redlsplay
hne

CONTROL-R Displays
a'#'andlh€n skipsro th€ nextlineanddispla!€th€currsntlin€wirh
editingalr6adypedormed.Thisenables
th€terminalop€ratorto seethe ellectsof
th€€ditingcharaclefs
€mer€dsinc€ths moslr€c6ntlin6terminalor.lf lh6 curent
lin€is €mpty,CONTROL-R
dlspla!€th€ praviousline Morcóv€r,
il an op€lator
snt€rsCONTROL-R
ssveralllm€s
successively,
th€T€rminalSuppoCod€dispLays
previouslin6s(skipping
thosethatconsistoJcariag€retum/lin6f66donly)unUllt
canlfind anymor6lines;then
ir fepeatedty
disptays
lh6 taEttinstoundforthe
r6maining
CONTROL-R's.

Emptytype

CONIROL-U lmmediarely
empiiesrh6typèaheadbufi€rrheTerminat
SupporrCodemanages.

Delete[n6

CONTROL-X D6l6tes
thecuffentline. CONIFOL-X
discardsattcharacters
entercdsincethe
mostfec€fi tin€terrnlnalor
andcauses,*'lo b€ display€d,

End ol fle

CONTROL-Z Terminates
Ìh€ curent in€(usedto signifyth66ndof fi16).CONTROL-Z
differs
fromCariagendurn andLineFe6din thatCONTROL-Z
do€snotbecomepartol
th€cur€ntline. Consequ6nlly,
€nt€ring
CONTROLZ causesa laskpendingon an
AgREAD
cellrohaveitsreadr6qu€stsarislt€d
whhouttransferring
th€€nd-ol,îte
charact€r
1olh€ waitingtask'sbuff€r,lf thischaraclsr
is th€ onlycharacl€r
on a line,
no chalactels
wittb€s€ntin r€sponsetoth€readrequesi.

Speciallin6
termlnatof

2-to

Non€

lerminatesth€cur€ntlin€wilhorÌinserng a carriag€return/line
t66dlntothe
teÍ tream. TheT€fminal
supporlcode fansfefsthissp6ciattin€t€fminator
10the
waitingtasks bufier,butit do€snot€xpandthelÌn€terminator
intoacariage
return/rh€f€€dpai.

DeviceDriversUsefs Guide

FEATIJR.ES
OF THE DRII'ER INTERFACES

2.3.2.2Controlling
Outputto a Termlnal
When sendingoutput to a tenninal,the Terminal SupportCode alwaysoperatesin one of
four modes. The current output modecan be switcheddynamicallyto any of the othet
output modesby enteringan output control characterat the terminal. The output modes
and their characteristics
are as follows:
Normal

The Terúinal SupportCode acceptsoutput from tasksand immediately
passesthe output to the terminalfor display. This is the default mode.

Stopped

The Terminal SupportCodeacceptsoutput from tasks(limited by the size
ofthe outputbuffer),but it queuesthe outputratherthanimmediately
passing
it ro the terminal.

Scrolling

The TerminalSupportCodeac{eptsoutputfrom tasks(limited by the size
ofthe outputbuff€r),andit queuesthe outputasin the stoppedmode.
However,rathe.thancompletely
prevettingoutputfrom reachingthe
terminal,it sendsa predetermined
number(calledthescrollingcount)of
linesto theterminalwhenever
an operatorentersan appropriate
oùtput
control chalactel a! th€ !€rminal.

Disca.ding The TerminalSupportCodediscards
atl outputfor the terminal,rather
queuing
than
it or passing
it to theterminal.
The followingoutputcontrolcharacters,
whenenteredat the terminal,changethe output
modefor the terminal.Like theinputcontrolcha.act€.s,
eachcontrolcharacter
described here is the default, and cach can bc rcplaccd with a diffcrcnt control charactcr
by means ofcontrol character redefinition (explained later in this chapter).

NOTI,
The outputcontrolcharacters
described
in thefollowingparagraphs
pcrformthcir intcndedop€rations
onlywhentheyappearin the input
stream.Theyhaveno effectwhentheyappearin the outputstream.

DeviceDriversUser'sGuide

2-11

FEATUR-ESOF THE DRT!'ERI\TERFACES

Defauh
Function

Charact€rls) D€scriotion

Discard
outp!î

mod6. lfth6 outpuiis notin discarding
outpd intoor outof discarding
CONTROL'O Plac€6
placesor.nput
mods,CoNTROL-O
irÌlodiscarding
mode. Onlhe oth€rhand,if
placesoúpLnintolhémod€hwasin
orfputis in discarding
mods,CONTROL-O
priorlo srìt€ring
discarding
mod€,

Stad
oLrtput

il ths lastoutpLrt
confol charact€r
was
CONTROL-Q Plac€soutpú intonormalmode. How6v€r,
ths oulpú mod6r6turnsto *hat it wasb€loro€nteringstopp€d
CONTROLS,
modo. Notstharthisimpliosth6following:
.
Th€CONTROL.S,
CONTROL-Q
B€quenc€
ah{a}€rstumsthgoutplltmode
to whal n was b€forgthe 6equ€n@was b€gun,
.
Th€CONTROL.O,
CONÍROL-Q
sequ€nc€
alwaysplacesoulputintonormal
mod€,

Stop
outplrt

mode,
CONTROL-S PlacesoLlputintostoppedmode. Howev€r,
if oulputwasin thediscarding
placos;t
CONTROL-S
leavesit in discarding
mode,buta subsequ€nt
CONTROL-O
in slooo€dmods.

ScroI one
lin€

CONTROL,Í Placesodpú irdoscrcllingmodó,tómpoarilys6tsthe scrcllcounttoone,sends
on€outpullinsto tha16rminal,
andplac€sodpllt ifnoslopp€dmod6.

Scroln
lines

CONTROL-W Placesoutputinloscrollingmodeandsendsn linesio ihe terminal(wh€ren is
th€curr€ntscfolllngcount),andplacesoutputintostoppedmod€.

2.3.3Software
ControlStrings
TheTerminalSupportCodeenables
youto setterminalmodesandinqr.rire
asto their
youusefor settingor inquiringis theSoftwareControl
currentsetting.The mechanism
String,asdefinedin theAmericanNationalStandards
Institutepublication
ANSI X3.64
(1979).Therearetwo kindsof SoftwareControlStrings:the OperatingSystem
Command(OSC)sequence
andtheApplicationProgmmCommand(APC)sequence.
2.3.3.1OSCSequence
TheOperatingSystemCommandsequence,
or OSCsequence,
is usedby a programor a
terminalope.atorto comrnunicate
with theOperatingSystem
via theTerminalSupport
Code. You can use OSC sequencesto set the mode ofthe terminal or to request
information about the current modes. The format of the OSC seouenceis as follows:

2-t2

DeYiceDrivers User'sGuide

FEATURES
OF THE DRI!'ERINTERFACES

The openingdelimiter(EscapeRightBracket)informstheTerminalSupportCodethe
datathatfollowsis an OSCsequence,
andtheclosingdelimiter(Escape
Backslash)
indicates
theendofthe sequence.
TheTerminalSupportCodecanb€ setup to acceptOSCsequences
asinputfrom the
terminaloperator,asoutputfrom a task(viaA$WRITEor S$WRITE$MOVE,
for
example),
from both,or from neither.The'Connection
Modes"sectionof thischapter
describes
howto setup theTerminalSupportCodeto acceptOSCsequences.
WhentheTerminalSupportCodeis setup to acceptOSCsequences,
it stripsthe OSC
sequence
from the inputor outputstreamandperformsthe desiredoperation.
2.3.3.2APCSequence
TheApplicationProgamCommandsequence
(or APC sequence),
ìsusedby the
Operatrng
System(in thiscase,theTerminalSupportCode)to sendintbrmationto an
programor terminal.For example,
application
to request
ifyou usean OSCsequence
inlormationaboutth€currentmodeofyour terminal,theTerminalSupportCode
responds
bysendinganAPC sequence
containing
the requested
information.Theformat
of theAPC sequcncc
is asfollows:

The openingdelirniter(EscapeUnderline) informsthe applicationprogram(or the
operator)the data that followsis an APC sequence,
and the closingdelimiter (Escape
Backslash)indicatesthe end of the sequence.
When sendingan APC sequence,
the Terminal SupportCode insertsthe charactersthat
makc up thc sequenceinto the terminal'sinput buffer,just as ifthe operatorhad typed
them. This allowsthe applicationprogam to read the characters.The APC sequenccis
echoedat the terminal if echomode is enabledla later sectiondescribesenablinsand
disablinsechomodel.

DeviceDrivers Use/s Gulde

T.EATURESÓF' THE DRI!'ER INTERT'ACES

2.3.4Modesof TerminalOperation
A terminal supportedby the Terminal Supportcode is governedby numerousmodesof
opcration. SomeoI thcsemodesapplydirecdyto the ienninal, and are irdependentof
the connectiona task usesto communicat€with the terminal. The remainingmodes
dependentirely upon th€ conn€ctionbeingused. The followingsectionsdiscussthese
modes.
A terminal operatoror a programcan set thesemodesby issuingOSC sequences.Figure
2-2 showsan overallsyntaxdiagam of the possibleOSC sequences.the remainderof
portionsof the diagramin more detail. When readingthe
this chapterdiscusses
remainderof this chapter,.ememberyou can combineindividualportionsof OSC
sequences
as shownin Frgve2-2.
Insteadofusing OSC sequences,
your programscan usethe A$SPECIAL or S$SPECIAL
systemcall to set most of the modesdescribedin this chapter. Thosethat A$SPECIAL
cannotset are notedwhen described.
When a terminalis attached(duringsysteminitializationor when loggingonto the
system),its defaultterminal and connectionmodesare thosethat were assigneddu.iîg
systemconfiguration.The valuesspeciliedin the Unit InformationScreenassociated
with
the terminal'sDUIB are usedas the defaultmodes.

2-14

DevlceDriYersUser'sGuide

I.EATURDSOF THE DRI}'ER INTER.FACES

Figùre2-2. ConpositeOSCSequence
Diagram

DeviceDdvers User'sGuid€

FE,{TURES OF THE DR]ì'TR INTERT'ACES

2.3.4.1 ConnectionModes
the modesthatdependon theconnection
to the terminal,rather
Thissectiondescribes
to a terminal
ùan on the terminalitself. with thesemodes,whenmulfipleconnections
via the first connection
exist,the terminalmightoperateonewaywhencommunicating
via thc sccondconncction.
anda differentwaywhcncommunicating
wordfor
Eachoîthesemodesrelatesdirectlyto oneor morebitsin theconnection$flags
the connection(asdefinedin the Extended|RMXII BasicI/O SSrtemCalh mantal
description
of theA$SPECIALsystemcall). Thenamesof themodes,the single-letter
wordto whichthey
identification
codesfor themodes,thebitsof theconnection$flags
correspond,
anda briefdescription
of theirfunctionsaregivenin Table2-1.
AssumingtheOSCcontrolmodeis setappropriately,
themodesa terminalinheritsfrom
a connection can be altered. The syrtax of an OSC seguencethat wiII change one or more
of these modes is as follows:

where

Indicates
thissequence
appliesto a connection.You mustinclude
thecolon(:) afterth€ C.

modeid

An ID letterfrom thelist of modesgivenin Table2-1.

decimalnumber

Thevalueto whichyouwantto setthe mode.Thisnumbermust
be of the character data type.

TabÌe2-1containsa briefdescription
ofthe modesandvalues.For a morecomplete
description,rei€r to the descriptionof A$SPECIAL in theExrende.d.
íRMXII BasicI/O
S$îem Callsfi nral

2-16

DeviceDriversUsefs Guide

FEATURES
OF THE DRIVERINTERT'ACES

Table2-1. Connection
Modes
ModeNam6

Input

Bir(s) Descdption
andValues
G1

Invalid€rtrv, Thisvalu€is reselved
lor frltursus€,
Transparert
mode, Inputis transrnined
to the requesting
task
w hoú b€inghn€edhedBeror€beinglransminod,
dala
accumulàes
in a bufisrunlilthenurnborof .hara.ters€qualsthe
numb€rrequested
by th6laskin ils readcall.
Linssditingmod6.Inpú l6mainsin the lin+èditbuffèruntila line
terminator
is ènl6r6d-Whil€in th€ liné-edit
buff€r.inoutcontrol
charact6rc
canb€ us6dlo €dittho inpú, In line-6dlting
rnode,the
(plus
T€rminalSuppon
inp'rtilnesto2S4charact€rs
Codefsstricts
a lineterminator,
suchas cariagereturnor linef€€d).lîan
op€raror
€ntersmor€than254chafactefs
b€loreataskmakesan
inpú request,
onlythefrct 254arepassedlo the r6questing
task's
bufier.Theremaining
characters
arelost. lfiherearemor€
charactèrs
thenrequèst6d
in th€bufferwhene linetB.minator
ls
entered,
onlylherequested
characiers
aresent.Theadditlonal
characters
remainln th€ buferJorth€neK inputrequestFlushmode. Inpulisfansmisedtothe requesting
laskwhhor,i
b€ingline€diied.Belorebeingtransmitted,
dataaccumulat€s
in a
buff€rufil an inpuîr€q|]€stoccurs(hal is,alask issu€sa read
reques0.Then,the numberoi charac-lers
requesled
is movedkom
theTefminal
SupportCode npulbufertothe requestinglasks
buffer,lf charac-teF
remainln the buf6r,theyaresav€dforth€
nextinputrcqu€st.lfnot enoughcharaclers
arein th€ buffer,lhe
y withallavailable
r€queslls r€tLrrned
immodiate
characl€rs,
withoutwaitingforth€ numb€rof charact€rs
r€qu€r€d.

E.ho

InputpaÍty
sening

TheT€ffninalSuooort
Codeechooscharaclers
to lho t6rmnal's

Forchalaclers
enleredattheterrnnal,thelerminalSupporlCode
setstheoarw bt to o.
fhe ferminalSupport
Codedoesnot alterth€ inputpariiybji.

parity
OutpLn
s6tting

Forcharaclors
sentto theterminal,lhe
TerminalSupport
Codesets
thoparitybitto zero,
ThoTorminalSupporl
Codedoesnot aherth6outputparitybii.

Outputcontrol

OSCconlrol

ÈT

TheTerminalSuppo(
andactson outputcontrol
Coderecognizes
charactors
in thg inpuistream,
TheT€rmlnalSupport
in
CodeignoresoLltpLlconlrolcharacters
the rnputsfeam.
andactson OSC
TheTerminalSupport
Coder€cogniz€6
sequenceslhat
app€arin 6ilh6rtheinputof outpú sfeam.
in the inpul
TheTerminalSuppod
Codeactson OSCsequgnces
in th€output
TheTer.,îinalSupportCodeactson OSCs€quencss
Th€T€rminalSlpport
Cod€doesnotacton anyOSCsequences.

D€viceDrivers User's Cuide

2-17

FEÀTURES OF THE DRIVER INTERFACES

NOTE
concurrently
to obtaininput
It is possible
to ùsetwo or moreconnections
from a single terminal. In such cases,the connection associatedwith the

modesin effect.This
lastactivereadrequestalwayshasits connection
meansthat ifcharacters
comein from theterminalbeforea[other
the
connection's
readrequesthasb€eníssuedto teceivethosecharacters,
areprocessed
in theTerminalSupportCode'sinputbuffer
characters
with thepreviousread
to theconnection
modesassociated
according
request.To preventdatalossor coruptionof datawhenusing
ensurethatread
with differentconnection
modesettings,
connections
reqùests
occurbeforedatacomesin from the terminal.
2.3.4.2TerminalModes
In addition to the modesa terminal inheritsfrom a connection,a terminal hasmodesthat
are the sameregardlessof the connectionusedto communicatewith it. This section
desqibestheseterminalmodes.
Most of the terminal modesrelatedirectlyto informationsuppliedas input to the
A$SPECIAL systemcall, either as one or more bits in the terminal$flagsword for the
connection,or as other wordsin the terminal$attributes
structure(reier to the description
of the A$SPECIAL systen call in the Extended.RMX Il Basic I/O SystetnCalb mat\ral lor
more informationaboutthis structure). IIowever,someofthe modeshaveno relation to
A$SPECIAL. The namesof the modes,the single-letteridentificationcodesfor the
modes,the bits of the terminal$flagsword to which they correspond(if applicable),and a
brief descriptionof their functionsare givenin Table2-2. The modesthat do not
correspondto optionsin A$SPECIAL are notedwith asterisks(+) h Table 2-2.
Assumingthat the OSC control mode is set app.opriately(seeTable 2-1),a terminal's
modescan be alteredusingOSC sequences.The syntaÌ of an OSC sequencethat changes
one or more of the modescoveredin this sectionis as follows:

2.18

Devlce
DriversUsefsGuide

FEATURXSOF THE DRIVERINTERFACES

Indicatesthissequence
applìesto a terminal.You mustincludethecolon
lr) aftertheT.

mode id

An ID letterfrom thelist ofmodesgivenin Table2-2.

Thisparameteris validonlyif the modeID is C, E, or Z. It is the decimal
representation
ofan ASCIIcode(if themodeID is C or Z) or thenumber
of anescape
sequence
listedin Table2-3(ifthe modeID ìs E)If themodelD is C, thisparameter
represents
a functioncodefrom Table
2-6. lf the modcID is M, it is thenumberof a terminalcharacter
sequence
listedin Table2-4. Ifthe modeID is Z, it is an jntegerfrom 0 to
3 thatspecifies
theindexinto the specialcharacter
array.Otherwise
it is
thevalueto whichyouwantto changethe mode,aslistedin Table2-2.

Device Drivers Usefs Guide

2-19

F'EATURES OF TIIE DRI!'ER INTERF"A.CES

Tsble2-2. TerminalModeslcontinued)
ID

8h(s)

andValu6s
0escription
1 = Halfduplex.

0 - Videodisplayterminaì.
(hardcopy).
1 = Prirìt€d

0 = No mod€mconnéc1€d.
toth6 hardware
bya modem,
1 = lh€l€rminalisconn€cîgd

4-5

Output medlum

handling

Fordriv€rsthat
supponlinkpelamel€ls,
th6ph)sicallinkmode
(lDN)*h€n 6nabl€doverid€sthissetring.(Bit15ofth€ physical
linkrÌeldenablèsanddisablesthat
mod6.)
0 = Driveralwayssstsinpú paritybit100. Thisyields8-bÌtdala.
1 = Dr v€rneveraherctheinpú pafilybil. Thisi€lds &bh dala.
2 = Driverexpeclsevenparityon inpui.fhis yislds7-bitdala.
3 - Driverexpectsodd parityon inpu,Ì.Thisyields7'bitdata.
driver,il an
ExceptfortheTerminal
Colnmunications
ConùolÌ€r
€nofocculswh€n€v€nor odd parìryis s€1,lhedriversotsthé
eighlhbitlo one. Erors inclld€la) a parity€rror,(b)th€ r€c€iv€d
slopbl hasa valLeof 0 (fa- ng eÍor). or (c)the previoLs
(ov€runero4.
characler
receivecl
hasnotyelbeenI'rllyprocessed
ForrheTerminal
drlv6r,ifa parity€ror
ComnìuncationsConùoller
is discarded.lf aftamingeÍoroccurs,the
occurs,thecharacter
(ootl)withouteror
characl€r
is raturned
as an &bit nullcharact€r

Outpú parity
handling

physicallink
Fordriversihatsuppoitlnk paramelers,lhe
mode
(lDN)whenenabledoveridesthissetting.
0 = Driveralwa)€setsoúprlt paritybitto0. ThisyioldsS-bit
data.
1 = Diveralwayssetsthe odpú parhybnto 1. fhis yi€ldsa bit
2 = D versetsoutpú paritybitto give6venpadty.lhis yields7-bil
dala,
3 = Driversetsoutputparitybitto giv6odd parity.Thisyi€ds7-bli
daìa.
4 = Driverdoesnotchangeparity.Thisyields&bil data.

NOTE
lfyou set input or oLîput parityro evenorodd, you musl sel both
of lhem to th6 sam€ value. That is, ifyou sei mode l0 R lo 2 or3,
lou musl also set mods lDWto th€ sam€ valu€.

2--20

DeviceDrivers User'sGuide

FEATURIS OF TIIE DRII'ER INTER.FACES

Table2-2, Terminal Modeslcontinuedì
ModeName

Bi(s)

Translation

Doscription
andValu€6
IndicSoswhstherth€ T€rminalSupportCod6 fcrthis lerminal
p€rflrms ianslaiion b€twoen ANSI Standad X3.64 escape
6€quencasand unjqueterminalchafaclsfE€quenc€s.
0 = Oo not €nablèkan6lation.
1 = Enabl€fanslation.

10-12
andorienlalion

Each bit in this throabl fi€lcicor6spondsto a diferent funclion.
Entsra valu€(G7) accordingly.
Bit lG-tgrminalaxis s€quenc€

0 = Listor eíl€f lh€ horizontalcoordinalofirsl,
I = Listor gnt€rÌh€ vorticalcoordinat€frst.
Brt11-hori.ontel
dis ori€ntetlon
incr€as6sftom
l6ftlo right,
0 = Numbeng of coordinates
froml€ítto right.
1 = Nlmbedngof coordinaies
d6cr.as6É
Bit 12-verticalaxis
o entelion
incr€as€s
lromtop lo bottom,
0 = Numbering
of coordinat€s
1 = Numboring
of coordinales
d€creas€s
ftomtopto botlom.

N/A

Inputbaudrate

srudure
fieldof l€rminal$atlributes
Cor€spondsto in$baud$rate
in A$SPECIAL.
0 = Notappliceble.
1 = Pedoman automatic
baudrale6€arch.
oth€r= Actualinputbaudrats,suchas2400.

corresponds
10ourSbaud$rate
fi6ldof rermina6anribules
srrucrure
inASSPECIAL.
0 = Notapplicabls.
1 = Us6th6inputbaudral€for oúpr.lt.
othor = Ac,tualoutpr,itbaud ratg,such as 9600.

Scrollingnumber

N/A

1oscroll$linss
fieldofl€rminal$allributes
sfucturein
Corr€sponds
lo sèndlo lhe
A9SPECIAL.
Specilythe numberof linesof oirtpLtl
t€rminal's
ths op6ralorenlerslhescrolling
displaywhsn€v€r
(defaultis coNTRoL-w)controlchafacler

Scrgenwdth

N/A

to lo',^,"ord€r
b,,t€ol x$!6sizef eldin A$SPEC|Ar
s
Corresponds
t€rminal$attrìbd€s
structure.Thisisth€ numberof charactor
poshions
on €achlineof lhe rcrminalsscreen.

Scr€enHeight

N/A

fsld in A$SPECIAL'S
Corresponds
lo high'orderbyteof x$y$sizs
sfuctur€.Thisis lho nuaaber
ol linoson th€
terminal$attribLJtes

Device Drivers User's Cuide

2-21

FEATURNS OF TIIE DRI!'ER INîERF.I,CES

Table2-2. TenninalModes(coÍtirued)
ID

Bit(s)

Description
andValu€s
s
Cor€spondsto tow-ord6rbyt6 of x$y$oísetfeld in A$SPECIAL
Thisvalusstartsth€ numbeing
terminal$attribut€s
Btructure.
s6qu6nc6on bom ax6s,

Cufsoraddressing ofbel
N/A

Corèspondslo high-ord€rb)î€ of x$y$ofiselfield in A$SPECIAL'S
lorminelsettib{n€s
structuro.fhis isthavalueto whichthe
numbering
of lh€ axesmust'fallbacLatt€rr€aching127.
to ffowcontrolbitin 6o€cialSmod€6
fr€ldof
Corosoond6
terminal$atÎribut€s
structur6
in A$SPECIAL.
Thisbit spècifies
rrhetheran ifit€llig€nt
communications
board(suchas an
ISBC544A,|SBC184/4a,ilSBC186/410,or |SBC184/soboard)
s€ndsllow conlrol charact€rsto or€v€ntinout bufturovedow.
0 = Disable
flowcontrol,
1 = Enablolowcontrol,

Specialcharaclsr D

Corespondsto sp€cialcharactsf
bil of sp€cial$modes
i6ld ol
ll yourdevic€supports
t€rnìinal$attributes
sructur€in A$SPECIAL.
specialcharaders(cufen|y,onryrheisBc 188/4a,isBc r 8a/56,
|SBC186/410,|SBC546,|SBC547,and|SBC548boardsdo),the
(d€fìn6d
d6vc€ cans€ndan interuplwhen€v€r
a specialcharacl€r
lalerìn thespecialaray)btped.
Wh€nSpeciaL
Modeis on,thed€vic€usesinterupislo
Characîor
informtheTefminalsuooon
codeîharsoecialcharaclefs
have
b€en6nier€d.lf a sp€cialcharacl€r
hasalsob€endsflnedas a
signalcharact€r(r€f€rlothedescription
of ASSPECIAL
inlh€
Enended|RMX Basicl/O SyslemCals manual),the lorminal
SupportCod6s6ndsa unitlorheappropriale
signals€maphore
as
soonas h rec€iv€slhe
specialcharacter
interupl. This€nablesthe
specìalcharacter
lo be processed
ah€adol charact€rs
inlho input
blffsr thatarcwaitingto b€ process€d,Ho\{ever,
the sp€cial
character
rèmainsin the inpd streamandrnustalsobe prccessed
in linewilhth€ r€stoflhe inoutcharacters,
llth6 spocialcharactér
is noî*sgn6d as a sgnalcharacter,
the
T€rminalSuppori
Codediscards
th€sp€cialchafacter
aft€r
feceiving
it.
Wh€nSpecialCharacrer
r.ode s off,the dovices6ndsspecial
characters
throughthe normalinpústream.
lhe sottingoflhis bit is aslollows:
0 = Disabl€
SpecialCharacl6r
Mod6.
1 = EnableSp€cialCharacter
Mode.
TheSpecialCharacler
HighWatermark(A)is us€din conjuncllon
withthisli€ldto controlSpecialCharaclsMode.

2-22

DeviceDriversUse/s Guide

FEATURES
OF THE DRT'ERINTERFACES

Table2-2. Terminal Modeslcontinued)
ModeName

8rt(s)

o$criptionandValu€s

Highwatermark

N/A

Cor€spondsto high$war€6ma*
fi€ldol rsrminal$anriblr€s
structure
in A$SPECIAL.
Thisfi6ldsp€cifi6sth6
numberofb),1es
thetgrminalcommunication
board'sbuffurmustcontainbelorethe
boards€ndsth€ fiow controlcharacl6rto slop input, [fhe
|SBCslaA board alwaysu6€sa valueof 20 for ihe highwaler
mark.lt ignorcslhisfi€ld.)

N/A

Cor63ponds
to lo $wat€r$mark
fioldol t€rminaloattribut€s
structurs|nA$SPECIAL.
Thlsleld Ép€cifssth€numberof bytes
thetsrminalcommunication
board'sbuffermustdropto bsforethe
boad 6€ndsth€ flow @nlfol charactefto *aft ìnpul. (Ths
|SBC5444 board alwaysuÉ6sa valusof 20 fÍ ùe low watermark.
It ignorssthisfrold.)

Staninpú

to lc$on$char
feld of terminal$attriblx€s
sructure
Corr€sponds
in ASSPECIAL
Thisd€cimalvalue
spscifesan ASCIIcharactor
thatthecommunicatìon
boardsendswhenth6 bulferdropstothe
lowwalermark.(lh6 iSBC54.44boardalwayss€ndsan XON

Stopinpú

Physical
llnk

to lc$offScha.
fr€ldof 1€rminal$attribut6s
structure
Corr€sponds
in A$SPECIAL.
Thisd€cimalvalue
speciî€sanASCIIcharacler
thatthecommuniaauon
boafdsèndswh6nth6 buffsrris€6lolh€
highwatermark.(The|SBC544Aboardalweysséndsen XOFF
N/A

fisldof rcrminal$anribuÌss
sruc1ure
Corespondsto linkgparamot€i
in A$SPECIAL.
of ths physical
fhis îeld sp€cif€scharact€ristics
linkbotween
thelerminalanda d€vic€,lt b notsupported
by all
drìv€f,lhis@ntrol
devicedrivers.When€nabl€dfor a supported
modsoverrides
theinputandoutputparitymodes(lDsR andw).
fho valu. in th€two low-ord6r
bhs{0 and 1)sp6cifesthe inputand
o!Îput parity,as bllows:
0 = No Pafrty
1 = lnvalidvalue
2 = Ev€nparity
3 = Odd parity
fh€ valuein the nen tuo bhs(2 and3) specÌfies
rhecharacter
l6ngth,aslollows:
1 = 7 bils/charactor
2 = 8 bils/characler
3 = Invalidvalue

DeYic€D Yersljser's Guide

F'EA.TURES OF THE DRI!'ER INTERFACES

Table2-2. Terminal Modes(curtirùed)
ModeName

Br(s)

Description
andValu€6
Thevalu€in th€nsÍ l\/\lobirs(4and5)indicar$fis numbsfof
stop bits,as follo\/sl
0=lBtopbn
1 - 1ll2 stopbits
2=2stopbÍ6
3 = Invalidvalu6
Bhs6ihrough14ar€resoN6dandshouldb€ settozaro.
*h6lh6rth6 physicallink
is enabledor disabled.
Bit 15sp€cifiès
ph!6icallink.Sattinglhe bittoO
S6tringthi6bnto 1 ènabléEth6
disables
th€foaturg.
ForthsTsrminalcommunications
contlollerdfiv€r,if a parity€rror
occufson inpLrt,
th€charad6,is discardod.lf a ra.rìing€rrof
(oOH).
occurs,thecharacter
is returned
as an 8'bhnullcharactef
is dilterenl
lhanth6 melhodused
Thismsthodof error.epoding
parityspecification
is in €fect.
whenth6lEnMlNAL$FLAGS

Specialhigh

N/A

fr€ldin lorminal$anbutos
Corespondsto spdhi$water$mark
whhth6
sfuctureof A$SPECIAL.
Thisfeld is u6edin conjunction
fi€ld(D)to @ntrolSp€cialChaacl€rMod€.
SpècialCharact€G
Whenthedevice'sinprJtbufferfrllslocofiainthe nurnberof
charad€rs
sp€cifedinlhisfeld, SpecialCharacter
Mod€is
€nabled(assuminglh€
fsld isturì6d on). llthe
SpscialCharact€r
nurnb€rof charact€rs
in th€d€vice'6inputbull€riElessthanth€
highwatsrmark,Sp€cialCharac-ter
Modeis disabled,eveniflhe
SpecialCharacler
fieldisturnedon.
lfth€ Sp€cialCharacter
feld (D)is lurnedoff,thisfi€d hasno

* Control

Modfiestheline.edit
cha€ctérandóútpif cóntrolchaÉcter
assgnments.nel€rto lhe 'ContlolCharacl€r
R€d€fnition'
seclion
fof morsinformalion.

Paksan escapesequencewith
alerminacharacl€r
s€quenceto
translate
orsimulateaterminafunction.Tables2-3and2-4listthe
valueslou canem6f, Relorto ths "TÉnslalion
andSimulalion'
sectionolthischapterbr mof6intormatìon.

I Corresponds
to an opton notavailable
viaA$SPECIAL.
ThéOSCOuerysoqu€nce
does
not r6luminformation
aboL'tthisoption.

2-24

DericeDriversUser'sGuide

FEATURESOF THE DRII'ER INTERFACES

Tablc 2-2. Tcrmhal Modcs
ID
SpecialAray

Bir(s)

DescrìplionandVal!6s
Correspondslo special$chararay of t€rminal$attribules
fr€ldin
ihat
A$SPECIALlhis aray canholdas manyasiourcharacl€rs
aredefn6dasth€dsvic€'ssp€cialcheraclers.
lf SpscialCharador
Mod6 is on (andih€ d€vic€supportsSpscialCharacte.Mod€),
typingaóyof thss€characl€rbal thè k€yboardgon€€t€s an
irìt€rrupt
thatimmediately
inicms lhe fsrr'inal SupportCodethat
a sp€cialcharacl€lhasb€en€ntsred.lf the charact€r
is a signal
it immediatoly.
lf
charactsr,lhè
TèrminalSuppoú
Cod€proé€ss€s
th€chalactdisn'ta signalcharact€r,
theTerminalSupport
Cod6
do€s nothingwfh th6 character,
Th€lormatofthiss€qusn€€
is Zn = m, wh6r6
m is en intsggfinù€ fang6G3,spscifying
lhis charadersindexln
lh€ so€cialcharac-tgl
arav,
ASCIIcoden is a decimalvalu€
oith€ soecialcharacì€r's
yóu musifillih€
lfyou defnelessthanlourspecialcharact€rs,
you
remaining
slotsol thearay withduplicates
ofthe lastcharacter
dsfin€,

TRANSI-ATION
AND SIMUI-ATION.The translation
andsimulatiorcapabilities
of rhe
TerminalSupportCodeenableapplication
programs
to performsometerminalfunctions,
suchas direct control of a terminal'scursor,settingtabs,and other functions,by usinga
table ofpredefined escapesequences.This sectiondescribesthesecapabilities.
IntelligentterminalsrecognizecertainASCII codes(usuallycontrol charactersor escape
codes)as instructionsto perform terminalfunctions. This sectionrefersto thesecodesas
terminal charactersequences.Unfortunately,the functionperformedby a particular
terminal charactersequencevariesfrom terminalto terminal. For example,one t'?e of
terminal might interpret a CONTROL-P as a Cursor fught; a secondtype ofterminal
might interpret the sameCONTROL-P as a CursorDown. As a result,an application
programthat usesterminalcharactersequences
to manipulateterminalsmustbe
modifiedwheneverthe programis usedwith a different t)?e of terminal.
The Terminal SupportCode recognizescertainescapesequences
(a sequenceof
charactersbeginningwiththe Escapecharacter)as instructionsto perform terminal
functions. Table 2-3 liststhe escapesequences
the Terminal SupportCode supports.
Theseescapesequences
remainthe sameregardlessof the terminalyou connectto your
you can useescape
system.To makeyour applicationprogramsterminal-independent,
seouences
to control vour terminal.

DeviceDriversUset'sGuide

2-25

FEATURES OF THE DRIVER INTERFACES

The TerminalSupportCodecantransÌate
thesedevice-independent
escape
sequences
into device-dependent
terminalcharacter
sequences.
How thistranslation
occursdepends
on an OSCsequence
suppliedeitherby an operatoror by an application
p.ogram.This
OSCseqùence
formsan association
betv/een
a terminalcharacter
sequence
andan escape
sequence.
If translation
for the terminalis tumedon,theTerminalSupportCode
replaces
with th€ equivalent
the escape
sequence
terminalcharacter
sequence.
If
translation
for the terminalis turnedoff, or ifno association
hasbeenformedbetweenthe
cscapcsequence
anda terrninalcharacter
sequ€nc€,
th€TerminalSupportCod€passes
the escape
sequence
unchanged
to theterminal.
TheTerminalSupportCodecanalsotranslatea singleescape
sequence
into multíple
terminalcharacter
sequences.
Thisoperationis usefulfor simulating
operations
thatthe
terminaldoesn'tsùpportdirectly.

NOTE
TheTerminalSupportCodetranslates
escape
sequences
into terminal
charactersequences
consisting
of a singlecontrolcharacter
or an Escape
followedby a singlecharacter.lfyour terminalrequiessequences
that
aremorecomplicated,
or thatrequùecharacters
otherthanEscapeasthe
fist character
in the sequence,
youcannotusethe TerminalSupportCode
for yoùrtranslation.Your tasksmustsendtheothersequences
directly.
Table2-4liststhe terminalcharacter
sequences
thatthe TerminalSupport
Codesupports.
The conceptof translation
andsimulation
centerson theinterrelationof threeitems:
terminalcharacter
sequencel
escape
sequence,
andOSCseqùence.
TerminaÌCharacter A sequence
ofcharacters
thatis terminal-dependent.
It is usually
Sequence
a controlcharacter
or an escape
code.Table2-4liststhe terminal
character
sequences
thatth€TerminalSupportCodesupports.
For example,
for a Hazeltine1510terminal,CONTROL-H(ASCII
hexcode8) is a terminalcha.actersequence
thatmeansCu.sor
Lefî. Escfollowedby CONTROLE (ASCIIhexcodelB 5) is
anotherterminalcharacter
sequence
that meansreadcursor
address,and soforth. For a different qT,eof terminal,the same
functionsmightrequirea differentsetof terminalcharacter
sequences.
AlthoulClall the terminalcharacter
sequences
of theHazeltine
1510aresupported
by theTerminalSupportCode,someterminals
havesequences
thatarenot supported.For example,
a Zentec30
terminalusestheseqùence
EscG 2 (ASCIIhexcodelB 4732)to
indicateblinkingmode.Thisterminalcharacter
sequence
is not
listedin Table2-4,andthereforeit is not supported.

2-26

DeviceDriversUser'sGuide

FEATURESOF THE DRIVERINTERFACES

EscapeSeq!€nce

A terminal-independent
sequenceof charactersbeginningwith an
Esccharacter.Table2-3 definesthe ANSI StandardX3.64 escape
scqucnccsthat the Terminal SupportCode recognizes.Each
escapesequencecorrespondsto a te.minal function. If translation
is turned on, wheneverth€ escapesequenceis sentto the terminal,
the Terminal Support Code replacesit with the functionally
equivalentterminalcharactersequence-Alternatively,the
Terminal SupportCode can either passthe escapesequenceto the
terminalas is, or it can discardthe sequence.

OSC Sequence

A sequenceofcharacterssentto the Terminal SupportCode to
establisha pairingbetweenrn escapesequenceand a terminal
charactersequence.As other se.tionsin this chapterexplain,OSC
sequences
can alsoset otheaattributesof the terminal and the
connecaron,
To sendan OSC sequcncc,an operatorcan placethe OSC
sequencein a file and copythe fle to :CO:, or a taskcan call
A$WRITE (or S$WRITE$MóVE) to sendthe OSC sequenceto
the terminal. (The opemtor cannotenter the sequencedirectly
from the terminal.) The Terminal SupportCode int€rceptsthe
OSC sequenceand establishes
the desiredpairin& regardlessof
whetherthe OSC sequencecomesfrom a file or a task.

PRXPARINGTHD TERMINAL SUPPORTCODE. OSC seouences
can be Dlacedin a
file andcopic.llo lhe terminal.or theycanbe issuedfrom a tàsk.To establiiha pairirg.
the followingconditionsmust exist:
r

There must be a connectionto the terminal,and it mustbe open for writing-

The OSC control bits for that connertionmustbe set to permit the Terminal Support
Code to recognizeand act upon OSC sequences
on output. This featurecan b€
configuredinto the systemwith the lCU, or a taskcan userhe ASSPECIAL or
S$SPECLA.L
systemcallsto enablethe I/O Systemto act on OSC sequences
on
output,

When theseconditionsexist,the operatorcan copya file containingOSC sequences
to the
terrninal,or a taskcan call A$WRITE to sendlhe OSC sequences
to the terminal
Regardlessofwhether the OSC sequ€nces
camefrom a task or from copyinga file to the
terminal,the Terminal SupportCodeinterceptsthe OSC sequence,removesit from the
input or output stream,and establishes
the desiredpairing.
SYNTAX. The syntaxof an OSC sequencethat establishes
one or mofe €scapesequence/terminal-character-sequence
pairingsis as follows:

DeviceDriversUser'sGuide

FE,A.TURES OF THE DRIT'ER INTERÍÀ.CES

where
T:

that thissequence
appliesto the terminal.You mustincludethe
Indicates
colon(:) aftertheT.

appliesto Escapesequences.
Indicatesthatthissequence

The rlumberofan escape
sequencc
listcdin Tablc2-3.

sequence
listedin Table2-4.
Thenumberofa terminalcharacter

For example,
suppose
a terminalinterpretsCONTROL-H(m=8 in Table2-4)asa
tcrminal character sequencethat causesthe cursor to move backvrard one position. Tablc

2-3showsthatthe TerminalSupportCodeusesthe escape
sequence
"EscI D" (n=3) to

meanthe samething. To establisha relatiooshipbetrveenm=8 for the terminal and n=3
for the Terminal SupportCode,the operatoror a task can sendthe followingOSC
sequence:
Esc I T: E3-8 Esc\
Then,if translationis turned on for the terminal (Esc] T: T= 1 Esc\), whenevera task
writes the escapesequence"Esc[D" to the terminal,the terminal'scursorwill move
backwardone oosition. Fisure 2-3 illùstratesthis situation.

-2--28

D€viceDriversUsefs Gùide

FEATURES
OF THE DRII'ERINTERFACES

l lN llllr)

Figùre 2-3. EscapeSequence
Translation

TRÀ.NSLATIoN. If trenslationis turned on for a terminal.translationoccurswhen a task
callsA$WRITE to write an escapesequence.Insteadof simplypassingto the terminal an
escapesequencethe terminal doesn'trecognize.the Terminal SupportCode intercepts
the escapesequenceand sendsthe equivalentterminalcharactersequencein its place.
This equivalenceis establishedby OSC sequences.
Translationalsooccurswhen a taskcallsA$READ to read a terminalcharactersequence
for which an equivalen!escapesequenceis establishecl.
Before translationcan occur,the operatoror the task must turn on Ìranslationfor the
terminalby sendingthe followingOSC sequence:
Esc I Tr T:1 Esc\
Table2-2 describes
all the terminalmodesthatcanbe cbanged.
If transhtion is turn€d off, the Terminal SupportCode doesnot interoeptescape
sequences.Instead,it passesthem on unchangedto the terminal. Changingthe "T= 1" to
"T=0" in the previousOSC sequenceturns off translationmode.
TRANSLATIONEXAMPLES. This sectionlistsseveraltranslationexamplesfor
H:rzeltine1510terminals.AlL numbersare in decimalurlessspecilìeclas hexadecimal.
Theseexamplesassumethe terminal'sswitchesare set to allow the Esc character(rather
than the tilde character)as the lead-incharacterof the terminalcharactersequence.The
that beginwith the
Terminal SupportCodecannothandleterminalcharactersequences
tilde character.Theseexamplesalsoassumethe followingoSC sequencehasbeenissued
to specifyinformationaboutthe terminal'scoordinatesystem:

(Horizontalcoordinates
listedfirst,horizontalnumberingincreases
left to right,verticalnumbering
increases
top to bottom)

Device Drivers User's Guide

2-29

FE.\TUR-ES OF THE DRI!'ER INTER.F'ACES

U:96,

startsat 96)
(A\is numbering

v=32,

(Axisnumbering
fallsbackto 32 afterreaching127)

x-80,

(Screen
widthis 80characters)

\-24,

(Screenheightis 24lines)

E6:49,

(Cursor-addressing
terminalcharactersequence
is Esc
coNTROL-O)

E31-47, (Terminalcharacter
sequence
to cleara line is EscCONTROL-O)
826-51

(Terminalcharacter
sequence
to deletea line is EscCONTROL-S)

Esc\
The "CursorPositioning"sectionofthis chapterprovidesmore informationabout setting
up the terminal'scoordinatesystem.
Example1. Movethe cursorto theposjtionX=2, Y=2.
Escapcleqlgqgg-1lllLì
Escl2;2H
(ASCII Hex code IB 58
32 3B 32 48>

TerminalCharacterSeouence(terminal)
E s cC o N T R o aL -a Q
(ASCII Hex code 18 11 61 61)

Example2. Clear the currentline from the cursorpositionto th€ end of the line.
Escaoeseouence(task\

Terminal CharacterSeauence(te.minal)

Escl0K

E s cc o N T R o L - o

(ASCII

(ASCll

Hex Code ìB 58

Hex Codé 18 0F)

30 48)
Example3. Deletea line.
Escaoeseouence
ltask)

2-30

TerminalCharacter
Seouence
(terminall

DeviceDrivers Usefs Gùide

FEATUR.ES
OF THE DRIVERINTERfACES

E s c [ 1 M
( A S C T TH e x c ó d e 1 8 5 8
31 4D)

Esc CoNTRoL-S
( A S C r rH è x C o d è1 8 1 3 )

SIMULATION. Simulationorcurswhen there is no singleterminal charactersequence
correspondingexactlyto a givenescapesequence.
Simulationis necessarybecausesome
terminalsmight not haveterminalcharactersequences
to pertbrm the functionsindicated
by certain escapesequences.Therefore,the Terminal SupportCode must simul.Ltethat
function.
Simulationis performedonly on output. That is, a taskcan call A$WRITE and simutation
will occur. Simulationdoesnot occutwhenthe task callsA$READ.
When a task callsA$WRITE to write an escapesequencecorrespondingto a simulated
iunction,the Terminal SupportCodeinterceptsthe escapesequenceand figuresout what
the taskwantsthe terminal to do. Then the Terminal SupportCode sendsa se.iesof one
or ftore terminalcharactersequences
that the terminaldoesrecognize,producingthe
desìredeffect. Figure 2-4 illustratesthis concept.

Figure2-,1.EscapeSequence
Simulation

For example,
suppose
theterminaldoesnot supporttabstops.If giventhe right
informationaboutthe terminal,theTerminalSupportCodecansimulatethe tabstops,
crealingtheimpression
theterminaldoesindeedsupporttabstopsasif it werea
tlpewriter.All theTerminalSupportCodemustdo to accomplish
thisis to

DeviceDriversUser'sCuide

2-31

FEATURESOF THE DRIVER INTERFACES

Rememberwhere the cursoris on the display.

Rememberwherethe tab stopsare supposedto be.

Be ablc to tcll thc tcrminal to movc thc cursorforward by one space.

In general,to supportsimulationof escapesequences,
the terminal mùst haveterminal
charactersequences
for the followingcursormovementsi
.

One positionto the right

One positionto the left

One position upward

One position downward

The Terminal SupportCodecannotsimulnteall the escapesequences
listedin Table 2-3.
It can simulateonly the sequences
numbered0, 1, 6-11, 13,15, 18-20,22,and 23.
SIMUI"ATION EXAMPLES. This sectionlists three simulationexamplesfor a
hypotheticalterminal (all numbersare in decimalunlessspecifiedas hexadecìmal).These
examplesassumethe terminalhasthe followingterminalcharactersequences
for cuasor
movement:
CursorMovemenl

Terminal( harncrerSeouenlq

Cursor up

CONTROL-L (ASCX Hex code0C)

Cursor down

CONTROL-K (ASCII Hex code0B)

Cursor left

CONTROL-H (ASC[ Hex code08)

Cursor right

CoNTROL-J (ASCtr Hex code0A)

Ir addition,the examplesassumethe lbllowing OSC sequencehasbeensent to translate
the right, left, up, and down cursormovements:
Esc I T: E2-10, E3:8, U4-I2, ti5:Ìl Esc\
Example
1 Movethecursortox-2,y=8(assumingthecurrentpositionjsx=1.y=5).
The escapesequences
will then be simulatedas iollows:

DeviceDriversUse/s Guide

FEATUR.ES OF THE I}R]VER INTERFACES

EscapeSequence
(Outoutfrom Taskl

TerminalCharacter
Sequence
(Actuall),
Sentto Terminal)

Esc[8;2H

CONTROL-J
CONTROL.K
CONTROL-K
CONTROL.K

(ASCIIHexcode1B
58 383B3248)

(ASCIIHexcode0A 0B 0B 0B)

Example2. Simulatetab stopsAlthough the termìnaldoeshavea terminalcharactersequencefor movjngto the right
(m = l0 in Table2-4,which correspondsto escapesequencen =2 in Table 2-3), it doesnot
supportfunctionsn= 10(advancilgto the nexttab stop) and n= 11 (settinga tab stop)
listedin Table2-3. Therefore,the Terminal SupportCode must simulatethesefunctions.
The followingOSC sequencesetsup îhe terminalto supporttabsl
E s c I T : E 2 = 1 0 ,E 3 - 8 , E 4 : 1 2 , E 5 : 1 1 , 8 1 0 : 1 9 2 , E 1 1 : 1 9 2E s c \
Before operatorscan set tab stops,they mustprovide the Terminal SupportCodewith the
location of the cursor. This can be doneby resettingthe terminal;that is, by sendingthe
following escapesequenceto the terminal:
Esc c

(n =0 ir Table2-3)

Resettingthe terminalworks only if the terminalhas a resettermiDalcommandand if the
operatorhasestablisheda relationshìpbetweenthat commandand the escapesequence
Esc c usingan OSC sequence(Esc] T:E0=m Esc\, wherem is the numberof a terminal
charactersequencelistedin Table 2-4).
Having done this,you can set a horizontaltab stopby enteringEsc [ 0 W at the terminal,
and you can advancethe cursorto the ner1tab stopby enteringEsc [ 1 L The Termjnll
SupportCode keepstrack of the Iocationsof the horizontaltab stopsaswell as the
positionof the cursor.
TABLE OF ESCAPESEQUENCES.Table2-3 lists the escapesequences
you can pair
with terminal charactersequences
by merìnsoî OSC sequences.The followingrenarks
applyto Table 2-31
. 'Ihe "Code"solurruìcoolainscodesusedin the ANSI X3.ó4documen!.
.

The expression"99"representsany decimalnumber. Unlessotherwisespecified,
omitting the numbercausesthe Terminal SupportCode to supplya defaultvalueof 1.

DeviceDrivers Usefs Guide

FEATURXS
OF THE DRN'ERINTEMACES

2-31

In somecases,you càn combinemultìple escapesequences
into a single,compound
escapesequence.The tableidentiliesthesecases.

The Terminal SupportCode can simulatethe escapesequences
numbered0, 1, 6
through 11,t3, 15, 18through20,22, and 23. The remaìningesoapesequences
can
only be translated.

In almoslall cases,usks issuethe escapesequences
by callingA$WRITE. The
exceptionsconcernescapesequences
7 and 18,and they are describedin the tabìe.

DeviceDriversUser'sGùide

FEATURXSOF THE DRII'ER INTERIACES

Trble 2-3. EscapeSequence(contlnued)
Cod€

EscapeSequenc6

î 0

Rrs

Escc

Rsturns
ihe terminal
to hsinitialslate.Thisconsistsof r6setting
the
horizontaltab
stopsto fourspacesapart,beginnlng
wfh rhefirst
spac€,andretuming
th6 cursorlo lh6 upporl6flcornerofih€
display.

îr

HTS

EscH

Setsa horizontaltab
at the curentcursorposrlion.

CUF

E s cf 9 9 C

MovesthecursorfoMardthèspècifiednumb€rol posiuons.

CUB

E s c[ 9 9 D

Movesth€cursorbackward
ths sp€cifrsd
numb€rol postions.

CUU

Movesth6cursorupwardthe sp€cif€dnumberofposhions.

CUD

E s c[ 9 9 I

Mov€sthecuÉordownward
ths sp€cif€dnumberof po6itions.

CUP

Esc f99 ; 99 H

Movesthecursortothepositionspecifìed
bylhe decÌmalnumbers.
posÌlion,andthe
Thefirslnumberspeciîesthevedicalcoordlnate
position.The
secondnumberspecifesrhehorizontal
coordinate
hÒrizÒntal
óordinatesa.onumb€f€dfom lefttoright,beginning
wth 1,andtheverlicalcoordinalos
ar€number€d
fromtopto
botiom,aso beginning
with1. lflh6 parameteG
areo.nitled,thls
sequonco move6 th6 cursofioihe

Esc[99; 99 R

uppe.leftcornèr

ofthe display.

Repodsthecoordinatos
ofih€ curontcursorpostion. The
TermlnalSuppon
Cod6pac6sthissequenc€intothetermnals
inputstreamln r€sponsetos€quence
number19,whichasksfor
thecursoiscoordinates.
Thefìrstnumberspecifies
lhe venrcal
position,
coordinate
andthe secorìdnurnb€rsp6cif€sthe
position,Thehorìzontal
horizontal
coordinate
coordinal€s
are
numbered
fiom l€ltto riqht,b€qinninq
with1, andthe vertcal
coordinates
arenumbersdfromtoplo bottom,alsob€ginning
wth
1.

CPR

CBT

îs

CHA

Esc[99 G

positionin th6 cur€ntline.
Movesthecursortothespecified

f 10

cHl

Esc[93 |

Movesthecursorforwardbyths spec\ednumb€rol horizontaltab
stops.Forexample,
ifthe specilìed
numbfi is 2,lhs cursormoves
foMardtothe secordtab stopthat1encoL1tels.

cTc

EscI0 w

position.Youcan
Sstsa hoizontaltabstopatth€currentcursor
combinethis
andanyoìherCTCescapes€quencetoforma
clmpoundCTCescapesequence.An exampleof sucha
combinodèequ€nco
i€ ESC[0;1 W,whiohsoisbothhorizontal
andverticaltab
stopsatthe cursorposition,

Movesthecursorbackward
byth6specif6dnumberolhorizonta
tab stops.Forexample,
ilth6 specifednumbgfis 2, th€cursor
moyesbackvardto thesecondlab stopit €ncount€rs.

t Funqon thatcanbe srnìulated.

DeYice
DriversUser'sGuide

FEATI]RNS OT' THE DRIVT"R INTNRI'ACES

Table2-3. EscapeS(quences(conlinued)
Code
12

EscapeSequence

crc

Setsa verticallabstopalrhe curenrcursorposhlon.Seelhe
description
ol escapesequence
number11.

'I 1 3

cTc

E s c[ 2 W

clearsa horizontaltab
stopit ther€is oneatth€ cufent cursor
position,Ss€th€d€scriplion
ol escap€sequonc€
number11.

crc

E s c[ 3 W

Clealsa v€rticaltab
stoplllhereis oneal lh6 curr6ntcursor
position.S6sth€d€scrlpion of escapesequenc6
numb€r11.

'I 1 5

cfc

E s c[ 4 W

Clearsall horizortal
lab slopson rh€linecontainlng
thecursor.
Seelhe descriptìon
of escap€s€quencenumber11,

cTc

E s c[ 5 W

C earsa I horizontal
andvedicaltab stops.Seethe description
of
escap€sequence
nurnber11.

crc

E s cl 6 w

Cearsallv€rlicaltab
stops.Seelhe descriplion
of gscape
sequence
numb€f11,

'I 1 8

DSR

E s c[ 6 n

AsksrhelerminalSupport
Codeto reporllhecoordinates
ofthe
curentcursorpostlon.Seesequen@numb€r7lo. a descriptlon

.I 2 Q

lBc

E s c[ 0 g

Clearsa honzontallab
stopilthereis oneatthe cutent cursor
position.YoucancomblnethlsandanyotherTBCescape
sequenc€
to lorma compoundTBCescapesequence.An
exampleot slch a combin€dsequence
ls ESC[0;1 g, rhich
clearsbothhorizontal
andverticaiab stopsfromthecurentcursor

fBc

Esc[19

Clearsa verticaÌtab
stopiflhercis oneat thecurentcursor
poéhion-Seelhe desd pt on ot escapesequoîc€number20.

'I 22

lBc

'I 23

TBC

E s c[ 3 g

ClearsaLhorizontaandvertlcaltab
stops.Seeth€description
of
escapesequence
number20.

TBC

E s c[ 4 q

C earsallvertical
tab stops.Se6thedescrprlonol éscapè
sequence
numbef20,

DCH

Es. I99 P

Deletes
thesp€cifednùmbsrofcharact€rc,
bèglnningarth€
cuffeTdcursoflocatron,

Taskssendthissequence
wilhthe number0to requestthèlD
numberof theterminal
to whichthe requesls beingsént Ths
TermlnalSupportCodelnterceplsthergquestand
r€rurnsrothe
requesring
taskan idenlicalsequence,
exceptthatthe number
0) isth€rsquestéd
lD numbor.
{whichis greaterrhan

Clearsallhoizornallabstopson the lin€conrainng the cursor.
Seelhedescrlplion
of escapes€qu€ncenumber20.

t FuncîionUratcal LJesimLrated.

2-36

DeviceDriversUsefs Guide

FEATURES OF THE DRIIDR INTERFACES

Table2-3. Escap€Sequen.es(.ontinùéd)
Code

EEcape
Sequence

Funclion

Esc[99 M

D6let6sth6
sp€cifr€d
numb€roflin€s,beginningat th€ tin6
containing
th6cursor-

ECH

Esc[99 X

n€pbcésth€spgcilî€d
numberot charactors
withblanks,
beginning
al thecur€ntcurEorlocation.

E s c[ 0 J

Plac€sblanksatallpo6itions
ftomthecursorlotheendof th€
display.Youcancombinethis
andanyoth6rEDescapesoquence
to formacompoundEDescap€sequence.An exarnple
olsuch a
combineds€quence
is ESC[0;1 J, whichcloersths sntiredisplay.

Esc[1J

Plac€sblanksat allpositions
fromth€ boginningol th€ displayto
th6 cursor.S6ethedescription
ofescapesequenc€number28.

E s c[ 2 J

Fillslhe entiredisplaywilhblanks.Seethedesc ptionol escape
sequenc6
numbef28.

E s c[ 0 K

Pìacesblanksat all positions
ftofi the cursorto lhe endof the line.
Youcancombineth s andanyothorEL€scapes€quenceloform
a compoundELescapesequence,An exampleol sucha
combineds€quence
is ESC[0;1 K,whichplacesblanks
throughoLllhelinecurentlycontaining
the cu.sor,

Escl l

Placesblanksat allposiuons
Jromth€ b€ginning
of th6lin€
Óntainingthecorsorto thè culsoritself.Seethe descipriónÒf
€scap€s€qu€nce
numbs 31.

E6c[2K

Placosblanksat allpGitìonsin tho linecontaining
thg cursor-Scc
thodesc ptionof €scapssequ€nc€
nurìb€r31.

tcH

EscI99 @

Insensfiespecif6d numt'erof blanks,b6ginningatÌhe locationof

Esc[99 L

Insertslhespecfi6dnumb€rol blanklin€s,béginningatth€
locaion of thecurcor.

Esc[99 U

Movesth6drsplayloMard
in a mulliple-pag€
fìleby th€ sp€cified
numb€rol pages.lf thespecifiod
numberof pag6sis 0,the
displaymovesto lhe nen pag€.

Esc[99 v

Mov6sth€d splaybackwardin a muhipl+pag€
fle byths specified
numb€rol pages.lî thespecified
numberol pagesis 0,the
displaymovesto th6pr€viouspage.

Esc[99

Movesth€dlsplaydownward
(forward)
byih€ specifiodnumberot
lines.llthe sp€cified
numberof linesls 0,lhe d splaymovesto the

Esc[99 S

Movesthedìsplayupward(backward)
bythespeciîednumberof
lines.lfth€ sp€cified
numbérof linesls 0.lhe dlsplaymovéslo the

SGR

Escf99 m

thislàblc.
Secthc @mmontfollowing

DeviceDrive$ Useds Guide

FEATURES
OF THE DRIWR INTERFACES

Table2-3. EscspeS€quences
{mrtinued)
Code

EscapeSequence
E s c[ 0 |

Escfll

Seeths commentfollowìng
thistabl6.

E s cl 2 |

Unloc*sth€t€rminal's
k€yboard,
allowìngallcharacters
to be

Escf3 |

Prevents
controlcharacl6rs
fromboingdisplaysd,
bú siÌllcauses
thosecharact€rs
to hav€theinormalelfec-ts.t

E s c[ 4 |

Causesoutputcharact€rs
to ovoMril€charad€rson thedisplay.*

E 6 c[ 5 |

S€€thecommentfollowìng
thistable.

E è c[ 6 |

Seethecommentlollowìng
thistabl6.
Se€th€commentîollowingthistable.

45
46

E s c[ 7 |

Rt\.1

E s c[ 8 |

Esc[9 ì

E s c[ l 0 1

Seethecommentfollowing
thisÌabl€.

E s c[ 1 1]

Séethe conînîodl
following
thistabl€.

E s c[ 1 2

Causescharactersto
be d splayedon theterminal's
displayscreen

Esc[13]

Seethecomrnorn
following
thistable.

E s cI t 4 l

Se€thecommentfottowing
thistabte.

E s cl 1 5 l

Seethecommentfolowingthistable.

Rt\,1

E s cf 1 6 l

Seethecommentbllowlngrhstable.

E s c[ 1 7 |

Seethecommentlollowinglhìstable.

E 6 c[ 1 8 |

Caùseshoizontaltabstopstoapplyoquallytoa] nes,rarherthan
on a line-by,Ìine
basis.r

E s cf l 9 l

causesdalaonthercfminas displayscre€nto b€ fearedas a
contrnuous
sfeam,lathgrthanas a colleclion
ofdisjoinl,
pag6s.r
nd€pendent

Esc[20 |

Prcv€nts
the lineleedcharacterfomaulomalica
ly p€lorminga
*
cariagereturnwhens€ntto thelerminal.

58
59

E s c[ 0 h

* Thisisthe normal(delauh)
settingfor mostterminals.

-2-38

DeviceDriversUse/s Guide

FEATURXSOF THE DRIYERINTERFACES

Table2-3. EscapeS€quences
Code
SM

EscapeSeq!ence

Function

E s ct l h

S€ethecommenllcllowingthistable.
prsventing
Locksth€t€rminalsksyboard,
characi€rs
ftombeing
received
whontheyaretypèd.

SÀ,1

Esc[3 h

Elablesthedrsplayol controlcharacters
for debJggingpu'poses.

E s c[ 4 h

Enablesodpúcharactersto b6 insertédin iho display,mlh6rlhan
alwaysoveMriting6xistingcharacters.

E s cl 5 h

Seethecommentfoliowing
thistable.

E s c[ 6 h

Seethecommenticllowingthislable.

stv

E s c[ 1 0 h

S€ethecommentlo lowingthislable.

Esc|1 h

Seeihecommentfo owÌngthisrable.

SeeihecommenifoÌlowing
thistable,
E s c[ 8 h

s[4

Prevenls
charadersÍronrDeirgdisplayed
on rhelerminalss!,eel
astheyarelyped.

Seeth6commentfollowng thislable,

lhislabl€,
Séethecommentfollowlng

Se€the comm€ntJollowrng
th s tabl6,

stt4

Esc[16h

/ingth stable.
Seelhecommentfollo'

EscflTh

Se€thocomm€ntlollowingthlstablo.

EscllSh

Causèshorizontaltab
stopsto applyonlytothelinéon whichthey

sr\.{

Causesdatato be tr€atedas a coll€ctonofdlsloint,independent
pages,Inthiskindofenvironment,
a terminaloperaortypicay
accesses
lhe variouspagesin a frleby pressing
keyssuchas 'next
pag€','previouspage',or'qo to paqe'.
Esc[20 h

performa carrage
CaLrses
the lineleedcharaclerloautomatically
returnwhensentlo lhetérminal,

Commsnl: Thismode(orsequence
buta descriplion
is
or flnction)is included
ior compleleness,
beyond$e scopeof lhis manual,Fordelais,referlolhe1979v€rsìonoflhe ANS|X3.64
sîanoafo.

fleviceDrivers Usels Guide

2.39

FEATURES OF THE DRI!'ER INTERFACES

TABLE OF TDRMINAL CHARACTERSEQUENCES.Table2-4 liststhe terminal
via osc sequences.The
charactersequences
that you cao pair with escapesequences
value"m" in the table is the decimalrepresentationof the codethe termjnal requiresfor
the givenfunction. As th€ table shows,ifthe functionrequiresa characterplus a lead-in
Escape,add 32 to the character'sdecimalrepresentation.Note that the ASCII code 1BH
(Escape)by itselfcannotbe the resultof a translation.
Recallthe assignmentportion of the proper OSC sequencehas the form En=m, wheren
is the escapesequencenumberand m is the terminal charactersequencenumber.

Tabl€2-4. TerminalCh.racterS€quences
TerminalCharacler
Sequenc€
or Sp€cialInstfttclions
0

Dlsablelhetranslation
ofescapesequence
n, Thatis,passtheescapesequ€ncethrough
to theterminalwilhoutTerminal
or simulatÌonSupportCodelranslalion

01H(CONTROL,A)

02H(CONIBOL-B)

1AH(CONTROL-Z)
27

Thist6rmÌnalcharacter
3equènce(1BH- Escape)
is nol supported.

1CH(FS)

lDH (GS)

1EH(RS)

1FH(US)

EscooH

Esc01H

159

Esc7FH

160,191

2.40

192

the escapesequence.
Simulat€

193

Discard
lhe escapesequénce.Tharis,do nottranslar€
or simulai€ii, anddo nol passir
on to theterminal,

DeviceDriversUser'sGuide

FEATURES
OF THE DRIVERINTERFACES

CURSORPOSITIONING. Before the Terminal Suppofi Code can monitor or control the
position of a cursor,it mustknow the coordinatenumberingconventionsfor that
terminal. The Terminal SupportCode hasits own "model"of the terminal coordinate
numberingscheme.As mentionedin Table2-3,this model is the following:
.

The horizontalcoordinatesare numberedfrom left to right, beginningwith 1.

The verticalcoordinatcsarc numbcredfrom top to bottom,alsobeginningwith 1.

Wheneverprogramsreler to cursorpositions,they shoùldusethis convention.
Although this seemsa reasonableway to refer to positionson a terminal screen,not all
terminalsusethis numberingscheme.But, the Terminal SupportCodecan translatethe
terminalnumberingschemeinto its own model,as long as the terminal numberingslheme
obeysthe followingrules:
.

The numberingof the axescan start at any point left or right, top or bottom.
However,the numberingofboth aresmust startwith the samepositivevalue.

From there,numberingof both &\esmust increaseby onesuntil (or unless)it reaches
127.

If lh€ numbcringoI an axisreaches127,it mustthen "fall back"to a lower positive
value;whereafter,it must againincreaseby ones.

If the numberingoiboth àriesreaches127,the numberingof eachmust fall backto the
samevalue,

Iî the terminalnumberingschememeetsthesecriteria,you can set up the Terminal
SupportCode (via OSC sequences)
to handlethat numberingscheme.The termìnal
modesF, U. V, X, and Y (as listed in Table2-2) enableyou to specifyinformation about
the terminal numberingconventions.Onceyou sendthe proper OSC s€quenc€s,
tbe
Terminal SupportCode translatesthe terminalnumberingconventionsinto its own
standardconventions.Then,your programscan use the Terminal SupportCode stàndard
conventionswhen referringto all terminals.
For example,supposethe terminalhorizontalpositions(that is, its columns)are
numberedleft to right as 80, 81,82, ..., 127,16,17,18,...,31. Also, supposeits vertical
positions(its rows) are numberedtop to bottom as 103,102,101,..-,E0. Finally,suppose
that when referringto a particularpositionon the terminal screen,you must specirythe
vcrtical position first, foLlowedby the horizontalposition. Note that this numbering
conventiondiffersfrom the Terminal SupportCodenumberingconventionsin the
folÌowingways:
.

The numberingon eacha\is startswith 80, rather than startingwith 1.

The numberingof the horizontalaxis,when it reaches127,dropsbackto 16before
resuminsits climb.

Derire Drirers Uscr's Cuidc

2-4r

FEATURES OF THE DRII'ER INTERFACES

The numbering
of theverticalaxisincreases
from bottomto top,ratherthan
increasing
from top to bottom.

The coordinates of a given screeo position are vertical coordÌnate fifst, then
horizontal coordinate, rather than being horizontal first and vertical second.

Althoùghthenumbering
convention
of thisterminalis unorthodox,
it doesobeytherules
listedearÌierin thissection.To setup thisterminalfor usewith the TerminalSupport
Code,youcanissuethefollowingOSCsequence:
Esc I T: F=5, U=80, V=16, X-64, Y-24 Esc\
The F=5 portion te[s the Tcrminal SupportCodc thc vcrtical coordinatcis calledout
first, the horizontalnumberingincreasesfrom left to right, and the verticalnumbering
incleasesfrom bottom to top. The U=80 portion specifiesthe stattingnumber,V= 16
indicatesthe "fall-back"value,X= 64 specifiesthe line length,and Y=24 specifiesthe
numberoflines on the screen. Refer to Table 2-2 for more informationabout thesc
modes,
Table 2-5 lists OSC sequences
you can useto set up the cu.sorpositioningand control
charactersof somecommonterminals. The OSC seouences
listed in the table do not take
full advantages
ofthe featuresofthe terminals,bur ifyou connectlhe lermiîals to an
Intel integratedmicrosystem,suchas the System310,theseOSC sequences
enableyou to
run thc RSAT systemanalysistest. You can add to theseseqùences
to supportnlore
featuresof the terminals.

Table2-5. ExampleOSCSequences
for CommonTerúinals
Hazehino
1500,
1510,1520,
950'

(OSCsequsnceopeningdelimiter)

l : T =1 ,

u=32,
Y=32,
x=80,
Y:24,

U=96,
Y=32,

x=80,
Y 24,

E3=08,

E 4= 1 1 ,

E4=44,
E6= 49,

E31=1€
'

2-42

D€scription

(Specify
coordinate
slstemol tefminal)
(Stading
valuéol numb€ings€quenc€
of bothaxés)
(FallbackvaluowhencLrrsor
positionr6aches127on €hhsraxis)
(Numberof characler
poshonsperline)
(Numb€rol linesperscrc€n)
(Cursorrlght)
(Cursorlefr)
(Clr|sorup )
(Culsofdowì)
(Cusorposiuon)
(Clearline,cursorto snd)
(OSCseqLrence
closìngdelimiter)

Hazeltine
andEx€clrtive
80 arerademarksofHazoltin€
CorooÉiion.Televid€ois a
fadenìarkof Televid€oSvstems,
Inc,

DeviceDriversUset'sGuide

FEATURTS
OF THE DRI!'ERINTERIACES

CONTROLCHARACTER
RIDEFINITION. An earliersectionof thischaoterlistedthe
defaultcharacters
assigned
to theline-editiîgandoutputcontrolfunctions.Thecharacter
assignments
for thesecontrolfunctionsarenot fired. You candynamically
assignany
controlcha.acterto a controlfunctionprovidedby the TerminalSupportCode,as
described
in thissectionIfyou assigna controlcharacter
to a controlfunction,the assignment
appliesonlywhen
thecharacterappearsasinplt from the terminal.ln particular,assigìinga newcontrol
character
to be the Escape
character
doesnot changethe EscapecharacterÌrsedfor
outputtranslation.It is still theASCII ESCcharacter,
bexadecimal
codelBH. Also,any
newEscapecharacter
youdefinecannotbe usedaspart ofan OSCsequence.
Thecharacters
youcanassignto controlfunctionsincludethefollowing:
Charac-t€r
coNTROL-@
coNÌaoL-A through
CONTROL,Z
ESC
FS
GS
RS
US
OEL

DecimalASCIICode
0

Hexad€cimalASCIICode
0

1-26
27
28
29

1- lAH
18H
1CH
IDH
1EH
1FH
7FH

31
127

The synt&Ìof theOSCsequence
usedto assigncontrolcharacters
to controlfunctionsis
as followsi

0996

where
T:

Indicatesthatthissequence
applìesto theterminal.You mustincludethe
colon(:) at theend.

lndicatesthatthissequence
appliesto controlcharacters.

The decimalrepresentation
of theASCIIcodefor thedesiredcontrol
character.Thisdeciural
valuecanbc in rhc rangc0-31or 127.
If thiscontrolcharacter
is alreadyassigned
asa signalcharacter,
this
assignment
to a controlfunctionis ignored.(Referto the description
of
A$SPECIALin the Erre ded|RMXII Baic I/O SystemCallr manualfor
informaîionon assigning
signalcharacters.)

Device Dri!€rs Use.'s Cuide

243

FEATURESOF THE DRIVER IN'I'ER!ACES

If this control characteris assignedto anothe.controÌfunction,this osc
sequencereassignsthe charactefto a new function.
A numberindicatingthe functionto assignto thc conlrol character.Table
2-6 lists thesenumbers,with their correspondingdescriptionsand defaults

For example,the followingsequencecancelsthe defaultassignmentof Rubout (DEL) as
the deletioncharacteranrl assignsBackspace(BS) in its place:
Esc I T: c127-0, c8-11 Esc\
Table 2-6, Mef|u of Codtrol Character Functions
Number

Abbreviai€dD€scription

D€fauh
Assignm€nl

Passcharacterlhrough

nol assigned
Allconlfolcharaclers
d lin+ €dh,èscap€,or,lputcontrol,
or signalcharactors
CONTROL,S
CONTBOL-O
CONTROL,O
CONTROL-W
CONfROL.T
CONTROL-U
Escapé(ASCll1BH)
CONIROL-J,
CONTROL-M
CONTROL-Z
CONfBOL.P
Rubout(ASCllTFH)
CONTROL.X
CONTROL,N

1
2
3
5
6
7
8
I
10
11
12
13
14

Stan oLtput
Discafdoutput
ScrollN lines
Scroll1 lin€
Emptytypeahead
bufer
Escap€
Linelerminator
Endof ll€
Quotenextcharader
Deletellne
Sp6ciallin6terrninator

2.3.4.3Usingan Auto-Answer
Modemwitha Terminal
The Terminal SupportCode supportsterminalsthat interfacewith an ExtendediRMX IIbasedapplicationsystemthroughan auto"answermodem. It doesthis by controllingthe
RS232Data Terminal Ready(DTR) lìne and by providingOSC sequences
to enable
handshakilgbetweena task and a terminalconnectedto a modem.
Ifyour systemcontainsa modem,you can configlre the BasicI/O Systemto support
nrodenr corrtrol (rcfcr to lhe Extended|RMX II Interactive Confrguratiott Utilíly Reference
Mant&l). Onceyo]udo this, the BasicI/O System,during systeminitialization,establishes
the initial link to the modem. Or, your taskscan useOSC sequenc€s
to establishmodem
mode (the M modelisted in Table 2"2),to break the link (hangup), and to reestablishthe
link (dial and answer). Other than theseoperations,tasksand terminalscommunicate
throueha modemas iflinked bv a dedicatedline.

2-44

DeviceDriversUser'sGuide

FEATURXSOF THE DRI!'ER INTERIACES

Thc followingdiagramillustrates
th€syntalofthe OSCsequences
relatingto modem
control.UnlikeotherOSCsequences,
onlytasksshouldsendtheseOSCsequences
to the
TerminalSupportCode.An op€mtorat a terminalshouldneversendthem.

where
M:

x l9!5

Irìdicatcsthal this scqucnceappliesto a modem. You must includethe
colon (:) after the M.
Causesthe Terminal SupportCode to answerthe phone (set the DTR line
active). This indicatesthat ihe task is readyto sendor releive data.

Causesthe Terminal SupportCode to hangup the phone(clear the DTR
line). This breaksîhe phonelink.

Queriesthe Terminal SupportCode for the statusof the modem. In
response,the Terminal Srpport Code sencìsan APC sequencein this
lorm:
Esc _ M:x Esc\
wherex is either "A" ìf the modemis answered(DTR active)or "H" if the
modemis hung up (DTR clear).

WA]T

Requeststhe Terminal SupportCodc to notify thc taskwhcn thc motlcm is
in the proper state(only the "W" is required). "W = A" requests
notificationwhen DTR becomesactive(causedby an operatordialing up
the modem). "W = H" requestsnotìficationwhen DTR becomescleirr
(causedby the operatorhangingup the phone).
When the modemis in the proper state,the Terminal SupportCode
insertsan PC sequenceof the followingform in the input stream:
Esc

M:x Esc\

wherex is either "An if the modemhasbeenanswered(DTR active)or "H"
if the modemhasbeenhungup (DTR clear).
The followingexampleillustrateshow a task can usethe OSC modemsequences
to
communicatewith a terminrl via a modem.

DeYice
DriversUser'sGuide

2-13

FE,TTI]RESOF THE DRTI'ERINTERFACES

through
Assumethat onetaskis dedicated
to monitoringthemodemandcommunicating
it. Assumeturtherthatthe taskhasa connection
is
to the modemandthattheconnection
openfor bothreadingandwritirg. Tlpicalprotocol(usingthe mnnection)is the
following:
1.

ThetaskwritesthefollowhgOSCsequence
to the terminal:
Esc I H:HEsc\
This secluence
hangsup the phone(breaksthe link). It is an initializationstep.

The taskwrites the followingOSC sequenceto the terminal:
Esc I c: T-1 , E-1 Esc\

This setstraÍsparentmode (so the taskcan later read a certainnumberof charactersor
wait until they appear)and turns off echoilg to the tcrminal'sslrccn. Thcscchangcsare
lbr this connectiononly,not for other connections(Ìfany) to the modem.
3.

The task writes the followingOSC sequenceto the terminal:
Esc I M:WAIT-AEsc\
This requesîsthat the Terminal SupportCode return a notification(an APC
sequence)when the modemhasbeen ansìxered(DTR becomesactive).

The task issuesa read requestto read sevencharactersfrom the terminal.
Eventually,\ùhenDTR becomesactive,the Terminal SupportCode insertsan APC
sequenceofthe followingform in the input stream:
E s c _M : A E s c \
Thìs messagemeansa terminaluser hasdialedup the modemand is readyto
communicate,

The taskwrites the followingOSC sequenceto the terminal:
Esc I M:l,lAIT=HEsc\
This causesthe Terminal SupportCode to sendthe APC sequence"Esc_M:H
Esc\" to the taskwhen the terminaluserhangsup.

The terminal and the taskcommunicateas if on a dedicatedline for as long cs is
necessary.However,wheneverthe task receivesinput, it must scanthe input for
the APC sequence"Esc_M:H Fsc\ .
During this time, the task shoùldoperatethe modem in transparentor flush mode,
rathcr than line-editmode. In line-editmode,eachline receivedfrom the mod€m
must be terminatedwith a line terminator (suchas a carriagereturn/line feed).
However,the last set ofcharacters(the APC sequence)will probablynot be
followedby a line terminator. Therefore,if the connectionis operatingin line-edit

2-46

DeviceDriversUsefs Guide

FEATUR.ES
OF THE DRIVERINTERFACES

mode,the applicationtaskwill neverreceivethe final hangupnrcssagcfrom thc
Terminal SupportCode.
7.

Eventually,the operatorhangsup the phone. When this happens,the Terminal
SupportCode insertsthe followingAPC sequencein the input stream:
E s c _M : H E s c \
lhis meansthe terminal userhashung up and the link is broken.

The task returnsto step2.

This protocol is offeredas a model and is by no meansthe only one possible.Note,
however,that only the task,and nevetthe terminal,shouldsendOSC sequences
to the
Terminal SupportCode for modemcontrol. This restrictiondoesnot apply to other OSC
sequences.
Under somecircumstances,
a task needsto find ou! whethera terminal is readyto talk to
the task via the modem. The taskcan ascertainthe stateof the modem(answeredor
hungup) by perforrningthe folìowingsteps,in order:
1.

Ca[ A$WRITE to sendthe followingOSC sequenceto the modeml
E s c I C :T - 1 ,E - l E s c \
This setstranspafert rnorJe(rJisabling
line editing) and turns off the echoingto the
terminal'sscreen.Note that this is for this connectiononly, not for other
connections
(if cn)) to the modem.

CaUA$WRITE to sendthe followingOSC sequenceto the modeml
Esc I M:QEsc\
This requestsinformationas to the statusofthe modem;that is, answered(A) or
hung up (H).

Ca[ A$READ to read sevencharactersfrom the modem. This receivesfrom the
Terminal SupportCode an APC sequenceofthe form:
Esc_ lt: x Esc\
wherex is "A" if the modemis answeredand "H" if the modemis hungup. This
techniquewill work becausethe Terminal SupportCodeplacesthe APC sequence,
withoùt a line terminator,at the front of the line buffer for the connectionwhere
data (if any) is awaitinginput requestsfrom the task.

After performingthesesteps,the taskcan restorethe connection'sline editingand echo
modesto their originalstates.

DericeDriversUser'sGuide

FEATUR.ESOF THE DRII'ER INTERIACES

2.3.4.4 ObtainingInformationabout a Terminal
ln additionto specifying
informationaboutyourterminal,youcanuseOSCseque[ces
to
requestinformationaboutthe terminal'scurrentsettìngs.The syntaxof theTerminal
thatrequests
informationabouttheterminalis asfollows:
QueryOSCsequence

where
Q

Indicatesthat this sequenceis a queryfor information.

In responseto the Terminal Query OSC sequence,the Terminal SupportCode sendsan
APC sequencethat lìststhe currenîvaluesof all modesfor a terminaland all modesior
the connectionthroughwhich the requestwasmade- However,it doesnot .eturn
informationabout the escape-sequence/terminal-character-sequence
pairingsor about
the input/output control characterassignments.
A task obtainsthe query informationby performingthe followìngsteps,in orderl
1.

Call A$WRJTE to sendthe followingOSC sequenceto the terminal:
Esc I Q Esc\
This queriesthe Terminal SupportCode for informationaboutthe terminal. In
response,the Terminal SùpportCodereturnsthe requestedinformationin the îorm
of an APC sequence(without a line terminator) at the front of the t)?eaheadbuffer
for the connection. If echoingmode is enabled,this informationwill echoat the
terminalwhen the task readsit.

2-18

CallA$READ to read the appropriatenumberofcharactersfrom the connection.
the numberof charactersreturneddeDendson the valuesofthe modes.and some
of thesemodes,suchas the input baudrate (I) for the terminal,can vary in length.
You shouldallow two spacesfor the "Esc_"at the beginning,two spacesfor the
"Esc\" at the end,and enoughspacesfor the modesifl between.A simple,safeway
to obtain this data is to read one byte at a time, until "Esc\'appears. The modes
are separatedby commasand packedtogetherwithout blanks. An exampleof a
returnedAPC sequencefollows:

DeviceDriversUsedsGuide

FEATURXS
OF THE DRII'ERINTERT'ACES

Esc_ CI T-2 , E:0 , R-0 ,lr-1 , O:0 , C-0 ;T : l-0 , H:0 , M=0, R=2,W-2, T-1 , F:0 ,
r - 9 6 0 0 , o = 0 , s - 1 8 , [ - 6 4 , y : 2 4 , U - 8 0 , v - 1 6 , c - l , J - 0 , K - 0 , t ' - 0 , Q =E0s c \

2.3.4-5Restricting
the Useof a Terminalto OnèConnection
If there are multiple connectionsto a terminal,you can sendOSC sequences
via any one
of the connectionsto "lock"the terminal. When you do this, the terminal is temporarily
restrìctedfrom communicatingvia any other connection.
Tasksthat communicatevia the filst mnnectioncan usethe connectionaccordingto how
it was opened,and I/O requeststhroughthat connectionare processednormally,
However,iftasks make I/O requestsvia the locked-outconnections,the Terminal
SupportCo.ie queuesthoseI/O requestsuntil the terminal is unlocked.
The syntaxofthe Lock and Unlock OSC sequences
are as follows:

Lockstheterminal,temporarily
preventing
I/O via otherconnections.

Unlocksthe termhal,allowingI/O to occurvÌaall connectioÍsto the
rermtnat

The only way to lock a terminal is for a task or a terminaloperatorto sendthe Lock OSC
scquence.However,there are two waysto unlock a terminal:
r

A task (via the connectionusedto lock the terminal) or the terminal operatoacan
sendthe Unlock OSC sequence.

A task can closethe connectionusedto lock the terminal

After a terminal is unlocked,the queuedI/O requestsare processedin the order in which
theywere queuecl.

DeviceDdvers Use s cuide

2-49

FEATT]RES OF THE DRI!'ER INTERFACES

NOTE
If thereis a chanceof a terminalbecoming
locked,tasksshouldusecare
whenusingBTOSsystemcallsto communicate
via otherconnections
to the
terminal.If the tasksinvokesystemcallssuchasA$READ and
A$WRITEwithoutspecifying
a response
mailbox,a deadlocksituation
couldoccur.
2.3.4.6 ProgrammaticallyInseningOatainto a Terminat's|nput Stream
A task can use an OSC sequenceto insert (stuff) data into a terminal's input stream. This

process
is usefulwhenoperators
mustenterlargeblocksof datathatvaryonlyslightly
from oneoccurrence
to the next.The synta!of theStuffingOSCsequence
is asfollows:

where
Sr

Indicatesthat this sequencestuffsdata into the input stream. You must
includethe colon (:) after the S.

text

Text (a maxìmumof 126characters)to be placedin the terminal'sinput
strerm. If the connection'sechomode is enabled,the sruffedrext displ.rys
on the screen.Ifthe connection'sline-editingmode is enabled,the
operatoacan edìt the stuffedtext.

Ifyou sendcompositeOSC sequences
(multiple OSC sequences
separatedwith
semicoÌons),the compositesequencecan containonly one StuffingOSC sequence,and
that subsequence
must be the last subsequence.

2.50

DeviceDriversUse/s Guide

The OperatingSystemsùpplies
a numberof complere
devjcedriversthatsupportmany
differentdevices.Insteadofwritingyourowndevicedriver,youmightbe ableto useone
ofthe Intel-supplied
devjcedÍiversto commùnicare
withthe devices
ìn yourappljcation
syslem.
Someof theseIntel-supplied
devicedriversfall into therandomaccess
or common
category,
somefall intoîhe terminalcategory,
andsomearecustomdrivers.Thischapter
Ìislsthe driversby category
andprovidesgeneralintbrmationabouteachdrìver.Table
3-1liststhe driversincludedwith theExtended
iRMX II package.
Table3-1. Intel.Supplied
DeviceDrirers
lype

DeviceDriver
iSBC208flexblediskdriver
MassStorageControll€r
(MSC)driveri
iSBX218Affexibte
diskdriver
iSBC220SMDdriver
|SBC186/224A
mulliperpheraldriver
iSSX251bubblem€morydriver
|SAC264bubblememorydriv€r
Lineprinterdriverlor|SBX350
Linepr nterdriverlor|SBC286/10(A)
SCSIdriverlor |SBC286/1mA
iSBC186/410termnaldriver
TerminalCommunicatìons
Controll€r
drtvèr
|SBC534lernÌnaldriver
|SBC5444termnaldrivér
iSBX351telminaldriver
8274terminaldriver
82530termÌnaldriver

Custom

Blte bucketdrivef
Sfeam tìledriver

* S u p p o r l s l h ei S B C 2 1 4 , I S B C 2 l 5 Ga,n . i S A X2 1 7 Cc ó n r r o t t è r st t.a t s os u p p o r r rsh e
i S B X 2 l S A c o n l r o l l e r w h ei tni s m o l n r e d o n i h e S B C 2 1 5 Gb o a r d .

DeviceDriversUser'sGuide

I NTEI-SUPPLIED DEVICE DRIVERS

3.1 RANDOMACCESSAND COMMONDRIVERS
This sectiondescribesthe randomaccessand commondriverssuppliedwith the
OperatingSystem.Thesedriversare designedaccordingto the guidelineslisted in
Chapter5 and they make useof the featuressuppliedby the I/O System'ssupportcode
for randomaccessand commondevices.
For informationon addìngany of thesedevicedriversto your appìicationsystem.refer to
the Extended.|RMX II Interactive ConfrgurcttionUtíIít! ReferenceManual.

3.1.1 iSBC@
208 DiskDriver
This driver supportsflexiblediskettedrivesconnectedto the iSBC 208controller. The
driver supportsup to lbur units (0-3)per controller.
The iSBC 208 flexibledisk driver
.

Supportsboth 8-inchand 5.25-inchdisks(single-or double-sided,single-or doubledensity).

Supportsthe READ, Vr'RITE,SEEK, SPECIAL,ATTACH$DEVICE,
DETACH$DEVICE. and CLOSE functions.

Acrceptsthe OPEN functionbur performsno operationsfor it.

This driver requiresa 1K byte block of memoryin the first megabyteto be reservedfor
useby the driver. You can speci$ the physicaladdressof this hlockwirh rhe ICU during
configu.ation. The defaultaddressis 1600HTrack formattingand volumechangenotificationare supportedvia the SPECIAL
runcfron.
The seekoverlapcapabilitiesof the iSBC 208 controllerallow seekoperationsto occur
concurrentlyon multiple units ofthc samcdcvice, llowevet, concurrentseekoperatlorÌs
cannottake placewhile any other operationis in progress.
Refer to the rSBC 208 FlexibleDí.skDive ControllerHardware ReferenceManual îor rllorc
irlormationaboutthe iSBC208controller.

3.1.2 MassStorageController(MSC)Driver
Thìsdriverprovidesthemeansto controlharddiskdrives.flexiblediskdrives,andtape
drives.It cansupporteitherthe iSBC215c boardor the iSBC214boardasthe base
controller.

DeviceDriversUser'sGuide

INTELSUPPLIED DEI'ICE DRI!'ERS

The iSBC 2l5G board controlshard disk drives. t he iStsX2lTC and iSBX 2l8A boards
can be attachedto this boa.d,via iSBX connectors,to provide tape and fleibte disk
support,respectively.The iSBC 214boardprovidesall ofthe iSBC 2156, iSBX 217C,and
iSBX 218A featuresin a singleboard. However,hard disksformattedwith eirher the
iSBC 215G or iSBC 214 controllerwill not work when connectedto the other controller.
This driver requires62 bytesofmemory in the first megabyîeto be reservedfor its use.
You can speci$ the physicaladdressof this blockwith the ICU duringconfiguration.The
defaultaddressis 1200H.

3.1.2.1
|SBC@
2t5GFeatures
TheiSBC2l5Gcontroller
supports
harddiskdrives(usually
Winchester
technology)
thar
are compatiblewith thc 5T506/412interfaceand connectedto the iSBC 215c controll€r.
The driver suppo.tsup to foùr unitsper controller.
For hard disks.this driver
.

Supportsthe READ, WRITE, SEEK SPECIAL, ATTACH$DEVICE, and
DETACH$DEVICE functions.

Acceptsthe OPBN and CLOSE functionsbut performsno operationsfor them.

Track formatting,volumechangenotificatior, gettil8 devic€charactcrisrics,
and gelling
and settingbad track informationare supportedvia the SPECIAL function.
Improveshard disk integrityvia rhe seek-on-detach
feature,in which the disk headsseek
to the innermostrylinder (which is usuallythe diagnosticcylinder)in responseto the
F$DETACH$DEV command.
'Ihe

seekoverlapcapabiiitiesof the iSBC 215Gcontroller allow seekoperationsto occur
on multiple unitswhile a DMA transferis occuúingon anotheaWinchesterunit.
Reièr to the iSBC 215 Geneic WihchesterDkk Contoller HardwareRekrcnce Manual lor
more informationaboutthe iSBC 215Gcontroller.

3.1.2.2
isBxn.217cFeatures
TheiSBX217CMagreticCartridgeTapelnterfaceBoardis an 8-bit,single-wide,
iSBXMULTIMODULE I/O expansion
boardfor installarion
on any8- or 16-bit
ìSBChostboardthathasan iSBXconnector.It providesan interfacebetweena
MULTIBUSprocessor
boardand l/4-inchmagnetic
cartridgetapedrivesthatcorresponcl
to the QIC-02interface-

DeviceD vers User's6uide

3-3

INTELSUPPLIED DE!'ICE DRI'ERS

to an iSBC2l5G winchester
WhentheiSBX217CMULTIMODULE boardis attached
up to four tapedrivesconnected
to the
diskcontrollerboard,thedriversupports
MULîMODULE board,althoughonlyonetapedrívecanbe attachedat a time. This
upe driver
.

Supportsthe READ,WRITE,SPECIAL,ATTACH$DEVICE,DETACH$DEVICE,
andCLOSEfunctions.

Acceptsthe OPENfunctionbut performsno operations
for it.

via the SPECL{Lfunction:
Thedriversupports
the followingsubfunctions
Format
Get devicecharacteristics
Rewindtape
Rcadtapcfi-lcmark
Writetapefile mark
Retension tape

Theor y HumanInterfacecommands
supported
for taped.ivesareATTACHDEVICE,
DETACHDEVICE,BACKUP,andRESTORE.After youissuea BACKUPor
RESTOREcommand,
the softwareautomatically
rewindsthetape.
Refer to the iSBX217CMagnetícCaftrdgeTapeInteface MultímoduleBoardHardwarc
Reference
Manuallor mor€informalionabouttheiSBX217CMULTIMODULE board.
3.1-2.3iSBXrx 2í84 Features
TheiSBX218Aboardcontrolsflexiblediskdrivesthatarecompatible
with the
54784/460interface.The driversupports
flexiblediskdrivesconnected
to an iSBX218,4
MULTIMODULE board,aslongasthat MULTIMODULE boardis attachedto an
iSBC215GWinchester
diskcontrollerboard.Thisdriver
.

Supports
8-inchflexibledisks.

Supports5.25-inch
flexibledisks.

SupportsDMA transfers.

Supportsthe READ,WRITE,SEEK SPECIAL,ATTACH$DEVICE,and
DETACH$DEVICEfunctions.

Acceptsthc OPENandCLOSEfunctionsbutperformsno operations
for them.

The driversupportsthefollowingsùbfunctìons
via theSPF-CIAL
fùnclion:
Formattingtracks
Getting devicecharacteristics
Vollme changenotification(supportedon 5.25-inchflexibledisk
drivesthat havea "door-open"signal)

3-4

DeviceDriversUseis Cuide

INTELSUPPLIEDDEI'ICEDRI!'ERS

The seekoverlapcapabilitiesof the iSBC 2l5c/iSBX 2184 controllersallow seek
operationsto occuron multiple disketteùnits,evenwhile a DMA transferoccurson a
Winchestcrunit. However,all seekopcrationson

NAME

A 14-BYIEarrayspecirying
thenameof theDUIB. Thisname
uniquelyidentifiesthedevice-unit
to the I/O System.Useonlythe
first 13trytes.Thefourteenthis usedby the I/O System.If the
nameis lessthan14characters,
it is extended
with spaces.
You assignthe namewhenconfiguring
yourapplication
system.
Later,youspecirythe DUIB namewhenàttachinga unitvia the
RQ$A$PHYSICATSATTACH$DEVICE
systemcall. Device
driversdo reador writethisfield.

FILE$DRIVERS

WORD specifyingfile driver validity. Sertingbir number ,'i"of this
word impliesthat the correspondingfile driver can attachrhis
device-unit.Clearingbit number"i" impliesthat the file dnver
cannotattachthis device-unit.

Thelow-orderbit is bit 0. Thebitsareassociated
with the file
drivers as follows:

DeviceDriversUsefs Gùide

DEI'ICE DRIVERINTERFACES

Bit'f'

File Driver

0
I
3

physical
stream
named

The remaining
bitsof thewordmustbe setto zero. Devicedrivers
do not readorwrite thisfield.
FUNCTS

BYTE specirying
the I/O functionvalidityfor thisdevice-unit.
Settingbit number,,i,,impliesthatthedevice-unit
supportsthe
corresponding
function.Clearingbit number"i',impliesthatthe
device-unit
doesnot sùpportthefunction.Thelow-orderbit is bit
0. Thebitsareassociated
with thefunctionsasfollows:
0
I
2
3
4

read
wtite
seek
special
attachdevice

detach device

open

Bits 4 and 5 shouldalwaysbe set. Every devìcedriver requfes
thesefunctions.
This field is usedfor informationalpurposesorìly. Settingor
clearingbits in this field doesnot limit the devicedriver from
performingany I/O function. In fact,eachdevicedriver must be
ableto supportany I/O function,either by pe.lbrming the function
or by returninga conditioncodeindicatingthe inability ofthe
deviceto perfolm tha! function. However,to provide accumle
statusinformation,this field shouldindicatethe device,sability to
perform the I/O functions. Dcvicc drivcrsdo not read or write this
field.
FLAGS

BYTE speciryingcharacteristics of diskette devices. The
significanceofthe bits is as follows,with bit 0 beingthe low-order
D[:

Biî
0
I

DeviceDdversUser'sGuide

Meaning
0 = bits 1-7are undefined
1 = bits 1-7aredefinedasfollows
0 = singledensity
1 = doubledensity

4-3

DEVICE DRT'ER INTERFACES

0 = singlesided
I = doublesided

0 = 8-inchdiskettes
1 = 5 l/4-inch diskettes

0 = standarddiskette,(track 0 is single-density
with 128-b)'tesectors)
=
1 not a standarddisketteor not a diskett"

5-1

Reserved;must be set to zero.

Ifbit 4 is setto 0. then a driver for the devicehasthe informationit
needsto read deviceinformationfrom track 0. Refer to
Appendixc for more informationabou!the forma! of slandard
diskettes.

4-4

DEV$GRAN

WORD speciryingthe devicegranularity,in byes. This parameter
appliesto randomaccessdevices,and to somecommondeviccs
suchas tape drives. lt specifiesthe minimum numberof bytesot
informationthe devicereadsor writes in one operation. If the
deviceis a disk,magneticbubbledevice,or tape drive,you should
setthis field equalto the sectorsizefor the device. Otherwise,set
this field equalro zero.

DEV$SIZE

DWORD specifyingthe numberofbytes of irformation the deviceuntt can store.

DEVICE

BY]E speci8/ingthe devicenumberofthe devicewith which this
device-unitis associated.Devicedriversdo not accessthis field.

IINIT

BYTE speciryingthe unit numberof this device-unit.This
distinguishes
the unit from the other units of the device.

DEV$UMT

WORD speciryingth€ device-ulit oumber. This nurrrtrr
distinguishes
the device-unitfrom the other units ìn the entire
hardwaresystem.Devicedriverscan ignore this field.

INIT$IO

WORD specifyingthe offsetaddressof the I nitializ.eI/O
procedureassociated
wiÌh rhis unit (the baseportion is the sameas
the baseof the DEVICE$INFO$P pointer). For user-written
customdevicedrivers,the usermust supplythis procedur€(and the
FIMSH$IO, QUEUE$IO, and CANCELJIO procedures).For
common,randomaccess,
and terminaldrivers(both userwritten
and Intel-supplied),the proceduresare suppliedwith the I/O
System.When filling out the DUIB, enter the namesof the
INIT$IO, FINISH$IO, QUEUE$IO, and CANCEL$IO procedures
to supplythis information. Devicedriversdo not accessthis iield.

DeviceDriversUser'sGuide

DEYICEDRIVERINTERFACES

FINISH$IO

WORD specifyingthc offs€raddressof the Finish I/O procedure
associated
withthisunit (thebaseportionis the sameasthebase
of theDEVICE$INFO$P
pointcr).Devicedriversdo not access
thisiield.

QUEUE$IO

WORD specirying
the offsetaddress
of the QueueI/O procedure
associated
with thisunit (thebaseportior is thesameasthebase
of theDEVICE$INFO$P
pointer).Devicedriversdo not access
thisfield.

CANCEL$IO

WORD specifingtheoffsetaddress
of theCancelI/O procedure
associated
with thisunit (thebaseportionis the sameasthebase
of theDEVICE$INFO$P
pohter). Devicedriv€rsdo not access
thisfield.

DEVICE$INFO$P

POINTERto a structurecontaining
additionaljnformationabout
the device. The common, random access,and terminal device

driversrequire,for eachdevice,a DeviceInformationTable,in a
particularformat.
Chapter5 liststhe structureof theDeviceInformationTableused
with common and random accessdrivers. ChaDtcr 6lists thc

structure
usedwithterminal
drivers.lIyou ari writinga custom
driver,youcanplaceinformationin theDevicelniormationTable
according
to theneedsof yourdriver. Spe.irya zerofor this
parameterif theassociated
devicedriverdoesnot usethisfield.

UMT$.
INI. OIiP

POIN'IERto a structurecontaining
additionalinformationabout
the unit. Randomaccess
andterminaldevicedriversrequie this
Unit InformaîionTablein a particularformat. Chapter5 describes
theformatfor randomacc€ss
dÍivers.Chapter6 descaibes
the
formatfor terminaldrivers.If youarewritinga customdevice
driver,placeinformationin thisstructure,
depending
on therreeds
ofyour d.iver. Specib,a zerofor thisparameterif the associated
device driver does not use this field.

UPDATE$.
TIMEOUT

WORD speciryingthe numberof systemtime units the I/O System
mustwait beforewriting a partial sectorafter processinga write
requestfor a disk device. In the caseof driversfor devicesthat are
neither disk nor magneticbubbledevices,set this field to 0FFFFH
during configuratìon.This field appliesonly to the device-unit
specifiedby tbis DUIB, and is ifldependentof updatingdone either
becauseof the valuein the FIXED$UPDATE iield of the DUIB or
by meansof the I/O SystcmA$UPDATE sysremcall. Device
driversdo not accessthis field.

DeviceDriversUseis Guide

4-5

DEVICE DRIVER INTERI'ACES

NUM$.
BUFFERS

WORD that, ifnot zero,both specifiesthe deviceis a random
accessdeviceand indicatesthe numberofbuffers of devicegranularirysizethe I/O Systemallocates.The l/O Systemuses
thesebutlersto pertorm data blockingand deblockingoperations.
That is, it guaranteesthat data is read or written beginningon
sectorboundaries.If you desire,the randomaccesssupport
routinescan alsoguaranteethat no data is witten or read across
track boundariesin a singlereqùest(seethe sectionon the Ur t
Inforúation Tablein Chapter3). A valùeofzero indicatesthe
deviceis not a randomaccessdevice. Devic€driversdo not access
this field.

PRIORITY

BYTE sp€cifyingthe priority ofthe I/O Systemservicetask for the
device.Devicedriversdo not accessthis field.

FIXED$.
UPDATE

BYTE indicatjngwhetherthe fi\ed updateoption wasselectedfor
the device-unitwhen the applicationsystemwasconfigured.This
option,when selected,causesthe I/O Systemto finish anywrite
requeststhat had not beenfinishedearlierbecauselessthan a full
sectorremainedto be written. Fi{ed updatesare performed
throughoutthe entire systemwhenevera time interval (specified
duringconfiguratìon)elapses.This is independentof the updating
indicatedfor a particulardevice(by the UPDATE$TIMEOUT
field of the DUIB) or th€ updalingof a parlicular tlcviccindicatc

TRACK$SIZE

WORD specifying
the size,in b),tes,of a singletrackof a volume
on theunit. If thedevic€controllersupports.eadingandrÀ.riting
acrosstrackboundaries,
andyourdriveris a random-access
driver,
placea zeroin thisfield ln thiscase,theI/O System-supplied
randomaccess
supportprocedures
placean absolutesector
numberin the DEV$LOCfieldof theIORS. If youspeci! a
nonzerovaluefor thisfield,therandomaccess
supportprocedures
guaaantee
thatreadandwriterequests
do not qosstrack
boundaries.
Theydo thisbyplacingthe sectornumberin theloworderwordof theDEV$LOCfield ofthe IORSandthe track
numberin thehigh-order
wordofthe DEV$LOCfieldbefore
callinga user-written
devicestartprocedu.e.Instructions
for
writinga devicestartprocedure
arecontainedlaterin thisclrapter.
set thìs valu€ to zero.

MAX$RETRY

5"14

For interrupt-driven
devices,
a WORD specirying
the meximum
numberof timesan l/O requestshouldbe triedifan error occurs.
Nineis therecommended
valuefor thisfield. Whenthisfield
containsa nonzerovalue,the I/O System-supplied
procedures
guarantee
thatreador writerequests
areretriedifthe usersupplieddevicestartor deviceinterruptprocedures
returnan
IO$SOFTconditionìn theIORS.UMfiSTATUSfield. (The
IORS.UNIT$STATUS
ficld is described
in the ^IORSStructure"
sectionoi Chapter4.)

DeviceDriversUsefs Guide

WRITINGCOMMONOR RANDOMACCESSDEI'ICEDRII'ERS

CYLINDER$SIZE For interrupt-driven
devices,
a WORDwhosemeaningdepends
on
its value.asfollows:
Therandomaccess
supportcodeneversplitsa reador
wite into a seek/reador a seek/write.Instead,either
it expects
thedevicedriverto requestseekoperations
whenever
a read/writebeginson a rylinderdifferent
from the oneassociated
with thecurrentDositionof the
read/writehead(expticitseeks),
or it expects
the
controllerto performtheseseeksautomatically
(impliedseeks).
TheI/O Systemautomatically
requests
a seek
operation(to seekto thc correctcylinder)before
performinganyreador write. The devicedriverfor the
unirmustcalltheSEEI($COMpLETE
procedure
immediately
followìngeachseekoperation.
Other

Any othervaluespecifies
the numberof sectorsìn a
cylinderon the unit. TheI/O Systemusesthis
informationto determinewhenit shouldrequestseek
operations.It automatically
requests
a seekoperation
whenever
a requested
reador wlite operationbeginsin
a differentcylinderthanthatassociated
with the
currentpositionofthe read/writehead.Thedevice
driverfor theunit mustcal theSEEK$COMPLETE
urc immediatelv followine each seek ooeration

5.4 DEVICEDATASTORAGE
AREA
The commonand randomaccessdevicedrjversare set up so that all data îhat is local to a
deviceis maintainedin an area ofmemory. The IMfiIO procedurecreatesthis device
data storagearea,and the other procecìures
of the driver atess and updale information
in it as needed. Storingthe device-localdata in a centralarea servesrwo purposes.
First, all devicedriver proceduresthat serviceindividualunits ofthe devicecan accessancl
updatethe samedata. The IMfiIO procedureDasses
the addressof the areabackto the
I/O System,which in turn givesthe aàdressro the orher proceduresof rhe driver.
'lhey

can then placeinformationrelevantto the deviceas a whole into the area. The
identity of the first IORS on the requestqueueis maintainedin this area,aswell as the
atlachmen!sta!usof the individualunits and a meansof accessing
the interrupt/message
task.

DeviceDriversUser'sGuid€

WRITINC COMMON OR RA,NDOM ACCESS DE\,'ICE DRIVERS

Second,
severaldevices
of thesamet'?e cansharethe samedevicedrivercodeandstill
suppose
twoiSBC214devices
usethe
maintainseparaledevicedataareas.For example,
procedure
device,
and
samedevìcedrivercode.The sameINff$IO
is calledfor each
eachtime it is calledit obtainsmemoryfor thedevicedata.However,thememoryareas
thatit createsaredifferent.Onlytheroutinesthatservìce
unitsof a particulardeviceare
ableto accessthe devicedata area for tbat device.
Becaùsethe commonand random accessdevicedriversprovide this mechanism,you
might alsowant to includea devicedatastoragearea in any customdriver that you write.

5.5 INTRODUCTION
TO PROCEDURES
DRIVERSMUSTSUPPLY
The routinesprovidedby the I/o Systemand that the I/o Systemcalls(INIT$IO,
FINISH$IO, QUEUE$IO, CANCEL$IO, and INTERRUPT$TASK/MESSACE$TASK)
constitutethe bulk of a commodor randomaccessdevicedriver. Theseroutines,in turn,
make callsto devicedependentroutinesthat you (if you are writing your own random
accessor commondriver) must supply. Thesedevice-dependent
routinesare described
here briefly and then are presentedin detaiì:
A deviceinitializationorocedure.This proceduremust pedorm any ìnìtialization
functionsnecessaryto get the devicereadyto processI/O requests.INIT$IO callsthis
procedure.
A devicefinish orocedure.This proceduremust perform any necessary
final processing
on the d€viceso that the devicecan be detached.FIMSH$IO cals this procedure.
A dexjcestart procedure.This proceduremuststart the deviccprocessingany possible
I/O function. QUEUE$IO and INTERRUPT$TASK/MESSAGE$TASK(the random
access-supplied
interrupt/messagetask) call this procedure.
A devicestooorocedure.For interrùpt-drivendrivers,this proceduremust stopthe
devicefrom processingthe currentl/O function,if that lunction could take an indetinite
amountof time. CANCEL$lO callsthe devicestopprocedure.
For message-passing
drivers,all I/O functionsare guaranteedto finish within a limited
îime. CANCEL:$IOdoesnot call this procedure;therefore,this proceduredoesnot need
to perform any operations.
A deviceinterrupt procedure.This proceduremustdo all ofthe derice-rJependent
processingthat resultsfrom the device'ssendingan interrupt/message.
TNTERRUPT$TASK/MESSAGE$TASKcallsthis procedure.
Figure 5-5 illustratesthe relationshipbetweenlheseproceduresand the hìgher-Ievel
procedures(INIT$IO, FINISH$IO, QUEUE$IO, and CANCEIJIO) suppliedby the I/O
Systcm.The remainingsectionsofthis chapterdiscussthe proceduresin detail.

DeviceDriver3Useis Guide

WRITING COMMON OR RANDOMACCESSDEYICEDRII'ERS

Chapter 8 also provides information about these procerJures. Rcfcr to that chapt€r for

specifics
on whattheprocedures
mustdo whenhandlingeachq?e ofI/O request.

E
E
E
lr]

Figure5-5, Relationships
Randod-Access
DriverProcedurcs
between

5.6 DEVICEINITIALIZATION
PROCEDURE
The IMT$IO procedurecallsthe user-writtendeviceinitializationp.ocedureto initialize
the device. The format of the call to the user-writtendeviceinitializationDrocedureis as
follows:
CALLdevice$init ( duib$p, ddata$p, statusSp);

where
procedure.You canuseanynamefor
device$init Nameof the deviceinitialization
procedure,
this
aslongasit doesn'tconflictwith otherprocedùrenames
andyouincludethenamein theDeviceInformationTable.
duib$p

POINTERto the DUIB ofthe device-unit
beingattached.INIT$IO
supplies
thispointerasan inputparameter.FromthisDUIB, the device
initializationprocedure
canobtainthe DevicelnformationTable,where
informationsuchasthe I/o oort address
is stored.

DeviceDriversUser'sGuide

5-17

WRITING COMMON OR RANDOM ACCESSDEITCE DRI!'ERS

ddata$p

POINTERto an areaof memorysuppìiedby therandomaccess
support
code.Thismemoryis the userportionofthe device's
datastoragearea.
You mustspecifythe sizeof this areaof memoryin the Device
InformationTablefor thisdevice.lle deviceinitializationprocedure
can
purposes
usethisdataareafor whatever
it chooses.Possible
usesfor this
dataareaincludelocalflassandbufferareas.

slot$id
status$p

POIN'|ER to a WORD that INIT$IO suppliesas an output parameter.
The deviceinitializationprocedu.emust return the statusof the
initializationoperationin this word. It shouldretùrn the E$OK condition
codeiî the initializatìonis successful.Otherwise.it shouldreturn the
appropriateexceptionalconditioncode. If initializationdoesnot complete
successfully,
the deviceinitialìzationproceduremust ensurethat any
resourcesit createsare deleted.

The deviceinitializationproceduremust do the followingl
.

It mùst initializeany driver data structuresot flags.
For mcssogc-passing
drivers,this proccdurcmust initializeth€ PORT$T and
SLOT$ID fields of the device'sdata storagearea. The deviceinitializationprocedure
must createa port, then store this TOKEN in the PORT$T field. This procedure
must alsoscaninterconnectspacefor the board instancespecifiedin the Device
InformationTable and return its slot lD to the SLOT$ID field. Inrel hassupplied
samplecodeimplementingboth ofthese stepson ReleaseDisketteNumber 19t
iRMX lI DemonstrationSoftwarethat comeswith your ExtendediRMX II package.
For a description of these examples,se€the Ereflded. íRMX II Nucleus User'sGuide.
Ifyou havea devicethat doesnot needto be initializedbefore it can be used,you can
use DEFAULfiINIT, the defaultdeviceinitializatiooproceduresuppliedby rhe l/O
System.Specilythis namein the DeviceInformationTable. DEFAULfiIMT does
nothingbut return the E$OK conditioncode.

It must resetthe board or device.Then it can wait for completionof the reset.
For interrupt-driven drivers,the deviceinitializationprocedurewill not receivethe
intcrrupt if the devicesendsan interrupt to indicatethe resetis complere.For such
devices,either the devìcestart or deviceinterrupt procedureshouldcontainspe.ial
codeto oroccssthc resetinterruDt.

5-18

Devic€DriversUsefs Gùide

WRITING COMMON OR RANDOMACCESSDEYICEDRI!'ERS

For mcssage-passintdrivers, the devÌceinitii ization prNedure will receive
initializationresponses
from the controller. Either this procedure,the devicestart,or
deviceinterrupt procedurecan processsuchresponses.

5,7 DEVICE
FINISH
PROCEDURE
The FINISH$IOprocedure
callsthe user-wtitten
devicefinishprocedure
to performfinal
processing
on thedevice,afterthelastI/O requesthasbeenprocessed.
The formatof the
callto thedevicefinishproce
U_
I < abw>

Driver
IInit Information
Device-unitInformation

So,ifyou enteredan abbreviation
of "ABC"anda nameof "High
SpeedABC,"yourscreenabbrevjations
wouldbe'D,ABC,
"U_ABC,"
and"I-ABC.,Thescreennameswouldbe "HighSpeed
ABC Driver,""HighSpeedABC Unit Information,"
and"High
SpeedABC Device-unit
Information."
#driver

9-ó

Thevalueyouspecifyhereindicates
the kind of driverthisis and
thusthekind of screens
to display.Thefollowingvaluesapply:

DeviceDdvers Usefs Guide

CONFIGURINGA USER-WRITTDNDEYICEDRIVER

Value

Drlver

lorminalSuppoft
d verwithoneifi€ruptl€v€l(seeFigures
$3,
98, and911 lorscre€ns)

lgH;,;ii#":i:"íJ"

tntsruplessMULTIBUS|andMULTTBUSFu tvlessage
Passing
Terminalsupport
drivsr(s€6Figuros95,98, and911

InteruptDrivsnRandomAccessSupporlandcommondÍvers
(s66Figur€s96, 99, and912 icr scrsenE)

MULTIBUS
tt FuttMessag€passingRandomAccessdevices.

Resetued

(seeFigures$8,911,and9i4 for Bcr€€ns)
Generaldriver

(3è6
* 't6fupr,€vE,s
Fisures
s.4,

#device

Thisfieldindicates
thestartof theinformationthat appliesto the
deviceinformationscreen.'lhis informationcontinues
until a
#endfieldappears.

#dev_aux

Thisfieldindicates
the numberof auxiliaryparameters
on the
deviceinformationscreen.Thisvaluecanrangefrom 0 to 20, If
thisvalueis four or lessfor terminalsupportdevices
or random
access
devices,
or 14o.lessfor generaldevices,
eachauxiliary
parameteris displayed
on a sepaaate
line,andtheparameter
namesyouspeci$iin the #d fieldsaredisplayed
theretoo. If more
auxiliaryparanìet€l
s arespecificd,
rhcparameters
aredisplayed
on
the deviceinformationscreenin rowsof fiveparameters
each.ln
thiscase,thereis no roomfor theparameternamesandif anyarc
entered,the UDSignoresth€m.
Wlen theICU generates
a system,
ìt placesthe auxiliary
parameters
from thedeviceinformationscreenin the
?ICDEVC.A28
or ?ITDEV"428fil€srlìarir crearcs(whcrc?
meansthecharacter
canvary),immediately
afterthe Device
lnformationstructure.The file that is actuallyaltereddepends
on
whetherthedeviceis a terminall?ITDEV.A28ìor a
random/common
(?ICDEV>A28)device.

#d01

Eachoîthesefields(#d01through#d20)identilyauxiliar,
paramctcrs
in the deviceinformationtable.Althoughthe
identifiersfor theseparam€ters
arefixed(D01throughD20),il the
auriliaryparameters
eachfit on a singleline,the 1- to 41-character
parameter
nameyouspeciryhete(as'parameter
name',
surrounded
quotes)
by
will be includedon the menuto describe
the
au-rilìary
Darameter.

DeviceDriversUseCsGuide

9.7

DEVICEDRII'ER
CONFIGURING
A USER.WRIT"TEN

Evenifyour deviceìnformationtablecontainstoo manyau\iliary
pffametersto includea parameternamefor each,youmustspeaily
the #d fieldfor a parameterifyou planto addhelpinformationfor
thàtfield. In suchcases,
youcanspeci! the #d fieldwithouta
parametername,asfollows:
#d03 You canalsomodiîytheparameternamesandhelpinformation
for thestandardparameters
thatnormallyappearon the devic€
informationscreenyouselected.For example,
ifyou aresettingup
a randomaocess
deviceandyouwantedto modifythe parameter
nameandhelpinformationfor the DS field (seeFigure9-5),you
couldincludethefollowinginformationin theinputfile:
llds -'Size

of Devíce Local Data [0-oFFFFH]'

l hisis the description
of theDS field. Youcanmodirythe other
fieklsin thesamemanner.
d01help

Thìsis thehelpinformationfor theparameters.You MUST
includeheìpinformationfor all parameters.
The UDS assumes
thatthehelpinformationendswhena # appearsat the startofa
subsequent
ìine,or whenthemaximumcharacter
countis reached.
The UDS displays
helpinformationwhenthe ICU userrequests
helpfor thecorresponding
parameter.Helpinformationis limited
to a maximumof 1024characters.

#end

This field designates
the end of the device,unit, or device-unit
ìnformation.

#unit

This field indicatesthe start of the informationthat appliesto the
unit informationscreen.This informationcontinuesuntil an #end
field appears.

#unit_aux

This field indicatesthe numberof auxiliaryparameterson the ùnit
informationscreen.This valuecan rangefrom 0 to 20. If this
value is 10or Ìess,eachauxiliaryparameteris displayedon a
separateline with the parameternamesyou specily.With more
than 10auxiliaryparameters,the parametersare displayedtwo to a
row, with no room for parameternames.
When the ICU generatesa system,it placesthe auxiliary
parametersfrom the unit informationscreenin the ?ITDEV.A28
or ?ICDEV.A2Sfiles it creates,immediatelyafter the Unit
lnlbrmation structure.The file that is actuallyaltereddependson
the rypeof device: ?ICDEV.A28 for commonand random devices,
?ITDEV.A2Sfor terminaìdevices.

9-8

DeviceDriversUse!'sGuide

CONFIGURINGA USER"WRITTENDEI'ICE DRI}'ER

#u01

Eachofthesefields(#u01through#u20)identiryauxiliary
parameters
in the ùnit informationscreen.Theidentifiersfor
thesepa.ameters
arefixed(U01throughU20). Ifthe auxiliary
parameters
eachfit on a singleline,the 1-to 41-character
psrameternameyouspeairy
here(as'parameter
name',
surrounded
by quotes)will be includedon themenuto describe
the
auxiliaryparameter.
Youcanalsousesimilarfieldsto changethepatameternamesand
helpinformationfor anyof thestandardparametcrs
ofthc unit
informationscreen.

u01 help

Thisis the helpinformationfor theparameters.You mustinclude
helpiÍformationfor all parameters.
The UDS assumes
thatthe
helpinformationendswh€na # appearsat the startof a
subsequent
line. The UDSdisplays
thehelpinformationwhenthe
ICU userrequests
helpfor thecorresponding
parameter.Help
informationis limitedto a maximumof 1024characters.

#duib

Thisfieldindicates
thestartofthe informatìonthatappliesto the
device-unit
screen.The device-unit
informationcontinues
until a
#cnd ficld is encountered.

#duib_aux

Thisfieldindicates
thenumberof auxiliaryparameters
on the
device-unit
infbrmationscreen.Thisvaluecanrangefrom 0 to 20.
Currently,theUDS doesnot supportanyauxiliaryparamete.s;
therelore,setthis field asfollo\,r's:

9.1,1.2Device
Information
Screens
Thissectionliststhe differentDeviceInformationScreens
thattheUDS cangenerate.
WhenaddingsupportfoÍ yourowndriver,choosethe screenthatmatchesthewayyour
driverexpects
the DeviceInformationTableto look. AII of thescreens
in thisgroupcan
alsocontainauriJìary
parameter
lines.You shouldsetup auxiliaryparamcterlinesiI
noneof theDeviceInformationScreens
listedcontainenoughfieldsto supporttheneeds
of yourdriver. Figures9-3through9-8illustratethe screens
available
via thettDS utility.
Figure9-3showshowonecolumnof auxiliaryparameter
lineslook ifyou do not addyour
ownparameternames.Figure9-4shtrws
thearxilìaryparameters
lookwhenmultiple
columnsareneeded.
Themeanings
ofthe individualfieldsin thesescreens
arethesameasthe fieldsin the
DeviceInformationTable. Referto Chapters5 or 6 for moreinfo.mationaboutthose
tables.

DeviceDriversflser'sGuide

9-9

CONFIGURINGA USER-WRIÎTENDEVICEDRII'ER

(D_xxx) One-Interrupt Terminal Device Infotnatlon

(DEv)

Device Nane {1-16 chars l
Nunber of terÌninals on this controller
Drlver Data Size [0-oFFFFH]
(ss)
Drivers stack size [0-oFFFFH]
(lNl)
Term_init Procedure Name f1-31 Charsl
(FIN)
Term_finish Procedure Nane l1-31 Chars
(SET)
Term_setup Procedure Nane II-31 Chars]
(oUT)
Tern-out Procedure Nane [1-3]. Charsl
(ANs)
Term_answerProcedure Nane [1'31 chars
(HAN) Term_hangupProcedure Name [1-31 Chars
(UTI)
Term_utility Procedure Nane l1-31 Charsl
(lL)
Interrupt Lever lEncoded Level]
(CHK1) Terrn-check for this Level [1-31 Chars]
(D01)
Auxlliary
1
(D02)
Auxiliary
2
(D03)
Aùxi1iàry 3
(D04)
A.uxiliary 4
(NT)
(DS)

00
00000H
00000H

000H
00000H

00000H
00000H

00000H

Figure 9-3. UDS DeviceInformation Screenfor One-Interrupt Terminal

(D xxx)
(DEV)
(NT)
(DS)
(SS)
(lNI)
(FIN)
(sET)
(oUT)
(ANs)
(HAN)
(UTI)
(Tr1)
(CKl)
ll L2)
(CK2)
(D01)
(D06)
(Dll)
(D16)

T\,ro-Interrupt Tèrninal

Device lnformarion

Device Name11-16 charsl
Nuber of temrinals on Èhls concroller
D r i v e r D a t a S i z e { 0 - o F F F F H I0 0 0 0 0 H
Drivers Stack Size f0-oFFFFHI
0oo00H
Tern-init Procedure Nane I1-31 Charsl
Term-finish Procedurè Nane [1-31 Chars]
Tern_setup Procedure Nanìe [1-31 Chars]
Tern_out Procedure Nane [1-31 Chars]
rerm_answer Procedure Nane [1-31 chars]
Term_hangupProcedure Nane [1,31 chars]
Tern_utility
Procedurè Nane [1-31 chars]
Fírst Inlerrupt
l-eve1 lEncoded level]
Tenn-check for First fevel [1 - 31 Chars]
second InLerrupr Level Itr.oded ]evel I
Tern-check for Second Level {1
31 charsl
00000H (D02)
00000H (D03)
00000H (D04)
00000H (D07)
00000H (D08)
00000H (D09)
00000H (D12)
00000H (D13)
00000H (D14)
O0000H (D17)
000OOH (D18)
OO000H (D19)

000H
00000H
00000H
00000H
00000H
oooooil

(D05)
(D10)
(D15)
(D20)

Figùre 9-4. UDS Device Information Screen for Tì*o-InternrDt Terminal

9.10

DeviceDriversUser,sGuide

00000H
00000H
00000H
oooooH

CONFIGURINGA USER.WRIÎ'îEN DEI'ICE DRII'ER

(D_xxx) Interrupt-less
I,IULTIBUSI and MULTIBUSII
Ternìina1 Device lnfornatÌor
(DEV)
(NT)
( D S)

(ss)
(INI)
(FIN)

(sEr)
(our)
(ANS)
(HAN)
(UTI)

(l,rTP
I
(cHK)
(D01)
( D 0 2)
( D 0 3)
(D04)

Fult Message passíng

Device Name [1-16 Charsl
Nurnber:of terninals on this controller
Driwer Data Size [0-oFFF|H]
Driwer Sta.k Size l0-OFFFzul
T e r m l n i t P r o c e d u r e N a m e| - j l C h a r s l
Tern-flnish
Procedure Nane l1-31 Charsl
Tern-setup Procedure Nane [1-31 Chars]
îern-out Procedure Nane [1-31 Charsl
T c r n a n s e e r P r o c e d u r e N a m el I - 1 1 c h d r s l
Tern-hangup Pr:ocedur:eNarDe[1-31 Chars]
Tèrn-utility
Procedurè Nane l1-31 Charsl
l.{essageTask Priority
[0- 255]
T e r m - c Ì è c ! P r o c F d u r eN a m e[ 1 - 3 1 c h a r s ]
Auxiliary
1
Auxiliary
2
AuxíIíaiy 3
Auxiliary
4

000
00000H

000
00000tl

00000H
00000H
00000H

Figure 9-5, UDS Device Informafion Screenfor Interrùptless Terminal D€vices

(D_xxx)
(DEv)
(IL)
(ITP)
(SS)
(DS)
(MJ)
(TNl)
(FIN)
(STR)
(STP)
(lNT)
(ITo)
(D01)
(D02)
(D03)
(D04)

MULTIBUSI Randon Access Devlce tnfornatlon
Device Nane [1-16 Chars]
Interrupt
Lever IEncoded Level]
lnterrupÈ Task Prioriry [0-255]
Interrupt
Procedure Stack Size [0-oFFFzu]
Device Local Data Size [O-0FFFFH]
Nunber of Units on this Device [0-255]
InltlallzaÈion
Procedure Nane [1-31 Charsl
FinÍsh Procedure Name [1-31 Chars]
stert Procedltrè NàÌne [1-31 chars]
Stop Procèdure Narne {1-31 chatsl
Interrupt
Procedure Nane {1-31 Charsl
Interrupr Time our {o-oFFFFHI
Auxilíary 1
Auxiliary
2
Auxiliary 3
Auxiliary
4

000H

000H
00000H
00000H
000H

00000H
00000H

Figure 9-6, UDS DeviceInformation Screenfor RandomAccessDevice

DeviceDriversUse/s Cuide

9-lt

CONFIGURINGA USER.WRITTENDEVICEDRI!'ER

( D_xxx )
(DEV)
(MTP)
(ss)
(Ds)
rNU)
(INI)
(FIN)
(STR)
(STP)
(MSG)
(MTo)
(MQL)
(BIN)
(BlD)
(D01)
(D02)
(D03)
(D04)

Device Nane [1-16 Chars]
M e s s a g eT a s k P r i o r i t y [ 0 - 2 5 5 ]
Message Procedure Stack Size [0-oFFFFH]
Device Local Daca size I0-oFFFFHI
N u r n b e ro f U n i c s o n t h í s D e v i c p [ 0 - 2 5 5 ]
Init Procedure Nane [l-31 Chars]
Finish Procedure Narn€ [1-31 chars]
Start Procedure Nane [1-31 Chars]
SÈop Procealure Narne l1-31 Charsl
Message Procedure Name [1-31 chars]
Message Tine out [O-0FFFFH]
Mèssage Queue ]-ength [0-oFFFFH]
Board Instance l0- oFFHI
Board ID. [1'10 chars]
Auxtliary 1
Au:iliary
2
Auxiliary
3
Auxiliary
4

000
00000H
00000H
000

00000H
00000H
000H
00000H
00000R
00000H
00000H

Figure 9-7. UDS DeviceInformation Screenfor MULTIBUS@II Message-Passing
Random
AccessD€vice

(D_x:x)

(DEv)
(IL)
(IîP)
(D01)
( D 0 2)
( D 0 3)
(D04)
( D 0 5)
( D 0 6)
( D 0 7)
( D 0 8)
( D 0 9)
( D 1 0)
(Drr)
(D12)
( D 1 3)
(D14)

ceneraf Device.

Device Infornation

Device Name [1'16 Chars ]
Interrùpt Lewèl IEncoded Lewel]
Interrupt Task Priority l0-2551
Auxiliary
I
Arlxiliary
2
Auxiliary
3
Auriliary
4
Auxiliary
1
Auxiliary
2
Auxiliary
3
Auxiliary
4
Auxlltary
3
Auxilíaty
4
Auxiliàry
I
Anxiliary
2
Auxiliary
3
Auxiliary
4
Figùre 9-8. UDS l)evice Inforúafion

9-12

000H

000H
00000H
00000H
00000H
00000H
00000H
00000H
00000H
00000H
00000H

00000H
00000H
00000H
00000H
00000H

Screen for G€n€rdl Device

DeviceDriversUseis Gùide

CONFIGURINGA USER.WRITTENDEVICEDRII'ER

9.1,1.3
UnitInlormation
Screens
Thissectionliststhe Unit InformalionScreens
thatthe UDScansenerate.Thesescreens
are defìnedbyplacinginformationìntoa userinpurfile.whichthàUDS reads.By
choosing
the appropriate
drivert)?e andaddirgthecorrectnumberof au\iliarylinesto
the driver'sscreens,
the usercansetup theICU to handletheconfiguration
of virtually
anydriver.All screens
in thisgroupcancontainauxiliaryparameterlines.If noneof the
Unit InformationScreens
listedcontainenoughlieldsto supportyourdriver,setup
auxiliaryparameter
lines.Figures9-9,9-10,and9-11illùstratethe screens
available
via
the UDS utility.
Themeanings
ofthe individualfieldsin thesescreens
arethe sameasthe fieldsin the
Unit InformationTable. Referto Chaoters
5 or 6 for moreinformationaboutthose
tables.

TernínaI
( DEV)
(NAl'l)
(cNF)
(TRF)

( rBR)
(0BR)
(sN)
(u01)
(u02)
( u 0 3)
(u04)
(u05)
(u06)
(u07)
(u08)
(u09)
(u10)

Support Unit

Infornation

Devlce Nane l1-16 chars l
Unit lnfo Name [1-16 Chars]
conn€ction flàgs IEncÒdèd]
Terninal flags IEncoded]
Input BAUDRate [0-oFFFrlì]
output BAUDRate [0"oFFFFH]
scroll Nrmber [0-OFFFFH]
Awil iory 1
Auxiliary
2
Auxil iary 3
Auxiliary
4
Auxiliary
5
Auxiliary
6
Auxiliary
7
Auxiliary
8
Auxil.iary 9
Auxiliary
10

000H
000H
00000H
00000H
00000H
00000H
00000H
00000H
00000H
00000H
00000H
00000H
00000H
00000H
00000H

Fisurc9-9. UDSUnit lnformatioriScreenfor TerminalDevice

Devicc Drivcrs UscCs Cuidc

9-13

CONF'ICURINC,1, USER-WRITTEN DEVICE DRI!'ER

(U_xxx)
(DEV)
(NAu)
(TS)
(l.fR)
(cs)

(u01)
(u02)
(u03)
(u04)
(u05)
(u06)
(u07)
(u08)
(u09)
(u10)

Randon Access Support Unit
Device Name [1-16 Chars]
Unit Tnfo Nane 11-16 Charsl
Track Siz€ [0-oFFFFH]
Ìlaxlnun Re!r1es [0-oFFFFH]
cyÌinder Size I0- 0FFFFHI

00000H (u11)
00000H (u12)
00000H (u13)
o0o00H (ul4)
00000H (u15)
0000oH (ul6)
00000n (u17)
0 0 0 0 0 H( u 1 8 )
0 0 0 0 0 H( u 1 9 )
00000H (u20)

lnfornation

00000H
00000H
00000H
00000H
00000H
00000H
00000H
00000H
00000H
00000H
00000H
00000H
00000H

Figure 9-10. UDS Unit ldformation Scrcen for Random AccessDevice

ceneral Devicè ljnit Infornation
( DEV)
(NAl'f)
(u01)

Device Nane l1- 16 Charsl
Unit Info Name[1-16 Chars]
Auriliary 1
( u 0 2 ) Auxitiary 2
( u 0 3 ) Auxiliary 3
(u04) Auxíliary 4
( u 0 5 ) Auxíliary 5
( u 0 6 ) Auxiliary 6
( u 0 7 ) Auxiliary 7
(uo8)
Auxiliary 8
(u09) Auxillary 9

(u10)

A$.iliary

00000H
00000H
00000H
00000H
00000H
00000H
00000H
00000H
00000H
00000H

Figùre 9-ll. UDS Unit Information Screelrfor General Devlce

9-14

DeviceDriversUsefs Guide

CONFIGURINGA USER.WRIITEN DEYICEDRIVER

9.1.1,4Device-Unil
Inlormation
Screens
This sectionlists the Dcvice-UnirInformationSc.eensthar rhe UDS senerates.When
addingsupportfor your own driver,choosethe screenthat marchestie wav your driver
expectsthe DUIB to look. Nonc of the scr€ensin this group currenttyal"í ou"itiary
parameterlines. Figures9-12,9-13,and 9-14illustratethe sqeensavailablevia the UDS
urility.
The meaningsof the individualfieldsin thesescreensare the sameas the fields in the
DUIB. Refer to Chapter4 for more informationabourthe fields of rhe DUIB.

(I_xxx)

TerÌnina1 Supporr Device-Unit

(DEV)
(NM)
(UN)
(UTN)
(l,fB)

Device Nane [1-16 chars]
Device-Unit Nane [1-13 chars]
Unlt Nurber on Èhis Device [0-0FFH]
Unlt Tnfo Nane 11-16 charsl
Max Buffers [0-oFFH]

Infornarion

000H
000H

Figure 9-12. UDS netice-Unit tnformation Screet for Terminal Device

All th.eeterminaldrivertlpesusethesameDevice-UnitInformationscreen.

Device Drivers User's Guide

9-15

CONFIGURINC.A. USER.WRIT'TEN DEVICE DRI\,'ER

(I xxx) Randon Access
(DEV)
(NAM)
(PFD)
(NFD)
( SDD)

(sDs)
(EFI)
(SUF)
(GRA)
(DSZ)
(UN)
(UTN)
(RUT)
(NB)

(cuP)
(MB)

Devlce-Unit

Infornatlon

Device Narde [1-16 Chars]
Device-Unit Nane [1-13 Chars]
Physical Flle Drtver Required lYes/Nol
Naned File Driver Required {Yes/Nol
Slngle or Double Denslty Dlsks IStngle/Doubre]
single or Double Síded Disks {Single/Doublel
8 or 5 lnch Disks I8l51
Slandard or Uniforn Format I Standard^ntforE ]
Granularlty
[0-oFFFFFH]
DevÍce Size i0'oFFFFFFFFHI
Unit Nurber on this Device [0-oFFH]
Unit lnfo Nane [1-16 chars]
Request Update Timeout Io-oFFFFH]
Nlnùef of Buffers lnonrandon : o/rand - 1-oFFFzu]
comon Update [Yes/No]
Max Buffers [0-0FFH]

No
Yes
Double
Double
5
Standarid
00000H
00000000H
000H
00000H
00000H
Yes
000H

Fizure9-13.Ut S Device-Unit
InformationScreenfor R4ndomAccess
Device

(I_iw)
(DEv)
(NAM)
(FD)
(FNC)
(FLG)
(cRA)
(DSZ)
(UN)
(INI)
(FIN)
(QUE)
(CL1'l)
(UIN)
(RUT)
(NB)
(sTP)
(CUP)
(MB)

Cenèra] Dewice-Unit Infornation
Device Name I1-16 charsl
Device-Unit Nane [1-13 Charsl
FiIe Drivers [o-oFFFFH Encoded]
Functions [0-0Fnl Encoded]
Ftags [0-oFFH Encoded]
Granularity
[0-0FFFFFHI
Devlce size [0-oFFFFFFFFF
Unit Nurber on this Device [0,0FFH]
lnitialize-I/o
Proc Nane [1-31 chars]
Finish-I/0 ProcedureNane [1-31 Chars]
Queue-I/o Procedure Name [1-31 chars]
cancel-T/0 Procedur€ Nane [1-31 Chars]
ùnit Info Name [1-16 chars]
Request Update Timeout [0-oFFFFH]
Nunb€r of Buffers [nonrandon : o/rand - 1-0FFFFHI
sèrvièe îask Priority [0-255]
CondronUpdace IYes/No ]
Max Buffers [0-oFFH]

00000H
000H
000H
00000H
00000000H
000H

00000H
00000H
000H
Yes
000H

Figure9-14.UDSDevice-Unit
InformationScre€nfor c€neÍù Device

9-16

DeviceDriversUset'sGúide

CON|IGURTNG
A USER.WRTTTEN
DEI'ICEDRIVER

9.1.t.5 hvoking the UDS Utility
Onceyou havecreatedan input file that specifieshow the screensfor your rJcvicerlrivcr
shouldappear,you are readyto invoke the UDS utility. To do this, ensurethat the
diectory containingthe UDS programalsocontainsthe UDS databasefile named
UDS.SCM. Then invokethe utility by tlTring:
UDS input- file

TO output-file

where:
input-file

The nameof the file that containsthe informationthat will be used
as input to the UDS utility. This is the file that wasdescribedin
the sectionentitled "UDS Input File."

output-file

The nameportjon of the output files generatedby UDS. UDS
addsthree-characterextensionsto thìs namewhen generatingits
output files. The two primary output files are output-file.SCMand
output-file.TPl-.You will use theseoutput files as input to the
ICUMRG utility. The other output file is outpuFfile.ljl a listing
flle that showsexactlyhow the screenswill appearwhen addedto
the ICU.
Note that you shouldnot nameyour UDS output files
ICU286.SCMor lCU286.TPL.

For example,supposeyou createdan input file calledNEWDRIVER.TXT and wanted
the UDS utility to generateoutput files calledSPECIAL.SCMand SPECIAL.TPL. To do
this,you would enter the followingcommandl
uds néwdriwer. cxÈ co speciàl

Partof theoutputof the UDSutilityaretwofileswith extensions
.SCMand.TPL(in the
example,
SPECIAL.SCM
andSPECIAL.TPL).Thesefilescontainthedefinitionsof the
ICU screens
for yourdriver.After runningtheUDS utiliry,youwill usetheICUMRG
utilityto addthesefilesto the ICU.
However,treforerunningfCUMRc, examinethelistingfile (in the example,
SPECIAL.LST).Thisfile showshowthedeviceinformationscreen,
the unit information
screen, and the device unit information screenwill look whcn addcd to thc ICU. If rhcrc

is a problemwith the appearance
of anyof thesefiles,youcancatchtheproblemeaù
andrerunIIDS. instea(lof addinsincorrects{'reens
to the ICU.

I)evice I) vers flser's Gùide

9-17

CONFIGURINC.{

U SER.WRJTTEN DE\,'IC[ DRIVER

9.1.1.6
UDSErrorMessages
Ifyou makea mistakewhencreatingthefilesto useasinputto UDS,the UDS utilitywill
generatean error messageand displayit on your screen,The followingerror messages
are displayedvrhenan exlernalîile or memorytlpe error occuru,and are precededby the
crrot mcssage:
***Error

in IJDS

The external file and memory t1rpeerror messagesare
.

*** cennor Are.h

Inn,rr FiIe

You did not have the proper permission to accessthe fle containing the UDS
rnsfrucÌrons.
.

***

not enough nemoly for buffers*

Your memorypartitionis not iargeenoughto permitthe UDS utilityto run.
.

*** Cannot Attach UDSSCMFile
UDS needsto accessa file calledUDS.SCM,but you do not haveread accessto that
file.

,t** Invalid uDs.scMFile
The UDS file UDS.SCM hasbeencorrupted.

***Cannot Create Ne\r SCMFile
UDS cannotcreatethe output file (output_file.ScM).

***Cennot

Create

New TPL Fi1è

UDS cannotcreatethe output file (output_file.TPI-).
.

***CannoÈCreate LST File
UDS cannotcreatethe listingfile (output_file.LsT).

In addition to externalfile and memorytype error messages,
the UDS producesinput file
erÍor messages,
which are precededby this message:

*)r* Error in UDSInput Flle on line

Where < line-number> is the line numberin the user input tile at which the error
occurred. lnput tile error messages
can be any of the following:

9-r8

*** Missing User Versíon

There was no #version statementin your UDS input file. This statementis required.
*** Tllegal Version

DeviceDrivers User,sGuide

CONFIGURTNG
A USER.WRITTEN
DEI'ICEDRIVER

The #versionnumberin the userinputfile is outsidethe legalrangeof 1 to 4
characters.
.

*,t* Missing User Device Nane
The #name field is not in the UDS inpur file. This srarement is required.

***

lllegal

Device Nane

The #nameidentifieris of0lengthor greaterthan25characte.s
in len$h.
.

***

Ulsslng User Devlce Abbr

Therewasno #abbridentiiierin yourUDS inputfile. Thisstatement
is required.
.

*** Illegal

The #abbr value in the userinput file is outsidethe legalrangeof 1 to 3 characters.
*** MissingUser Driver Type

Device Abbr

The #driver identifier is missingfrom the userinput file. This identifier is required.
.

*** r1legal Driver TyPe
The #driver valuein the userinput file is outsidethe legalrangeof 1 to 7.

*** Missing úser Device
The #device identifier is missingfrom the userinput file. 'lhis identiiier is required.

*** Missíng Nùnlberof Dèvice Auxilíariès

The #dev_auxidentifier is missingfrorn the userinput file. This identifier is.equted.
*** llissing usef unit
The #unit identifier is missingfrom the userinput file. This identifier is required.

; t l * M i s q i n s r , J u r h è rn f t - i .

a,r\lIlaries

The #unit_auxidentifieris missingfrom theuserinputfile.
.

:t** Missing ljser Duib

The #duib identifieris missingfrom theuserinpurfile.
.

)t** Missing Nunber of DUIB auxiliaríes

The #duib auxidentifieris missirgfrom theuserinputfile. Thisidentifieris
requied.
.

***

DUIB Screen Can Not Have Auxiliary

Fièlds

The #duib aùÌ valuein the userinputfile is setto a vaÌueotherthanzero(0).
.

*** Missing Equal Sign
The equalsignis missingf.om an identifier that requies one.

*** Line Too Long

Devic€ Driv€rs User's cùid€

9.r9

CONFIGURINC A USER.WRII'TEN DEVICE DRIVER

A line in theuserinputfile is longerthantheallowable132characters.
.

*** Mlssing Auxiliary

HeIp Message

line wasaddedwithoutits requi.edhelpmessage.
An auxiliaryparameter
.

***

Auxiliary

]-ine Out of

Sequence

beginning
with line 01.
Auxiliaryparameterlinesmustbelistedsequentially,
.

***

Lines than Expected

Less Auxiliary

vaÌueof
The numberof auxiliarylinesis lessthanthevalueindicatedin the)m(_aux
the userinputfile.
.

***

llore

Auxilíary

Lines

than

Expected

The numberof atrtilìary linesis more than the valueindicatedin the )oo.auxvalùeof
the userinputfile.
.

:t** ll1egal

Tnput

Extra characters were entered on a line after the valid input.
.

***

Invalid

Abbreviation

Theabbreviation
for an auxiliaryfield is outsidethelegalrangeof I to 3 characters.
.

***

Abbrevialion

Not Found

When changing a standard parameter line or its help message,the abbreviation was
entered incorrectly.
.

***

Ntrlrber Exceeds ltlaximur

The value of dev_aux or unit_alx is grealer than 20.
.

*t(*

N"m}|pr

F vnp.iaíl

valuewasentered.
A non-numeric
.

***

Syntax Error

The openingquoteon a paramete.namelineis missing.
.

*** Do Not Use /l Sígn in Text
A parameternamecontainsa pound symbol(#).

*** Do Not Use ( Sign in Text
A parameternamecontainsa left parenthesis"(".

***

ì,liésilrg

End of

Text

Sign

The closingquote on a parameternameline is missing.
.

)k**

îpYr

lina

T^n

l^n'

A parameternameexceeds41 characters.

9-20

DeviceDrivers UserJsGuide

CONFIGURING A USER.WRJTTEN DE\TCE DRIVER

***

Help l{essage is

too

LonS

The Helpmessage
youenteredexceeds
1024characters
in len$h.
.

***

Field

Name ExPected

A blank line was detected iî the device, unit, or duib information.
.

*** UnexPected eof

The userìnputfile ìs incomplete.
The followingerrormessage
indicates
thatthespecified
file or directorylacksreador
creationpermission.
.

*)k*-IlO
,

Frrnr

ín

I'íla

fr f i l

_e-nanel

9.1.2 ICUMRGUTILITY
After usingUDS to generate
.SCMand.TPLfileslor yournewdriver,invokethe
ICUMRG utility to combinetheinformationin thesefileswith the informationin the
ICU286.SCM
andlCU286.TPLfiles(thefilesthatcontainthe definitionsof all theother
ICU screens).BeforerunningICUMRG,makesurethatICU286.SCM
andICU286.TPL
residein the samedirectoryastheICUMRG command.Then,invoketheICUMRG
utility asfollows:
ICUMRGinput

file

T0 output-file

Where:
input'file

The name(minusthe extensionpart) of the .SCM and .TPL files
generatedby the UDS. For example,if the UDS utility created
files called SPECLA.L.SCMand SPECIAL.TPL, you would specify
the nameSPECIAL here.

ourPur-file

The name(minusthe extensionpart) of new ICU iiles that
ICUMRG will create. For example,if you specifiedthe name
ICUNEW, the ICUMRG utility tri[ createfl€s caled
ICUNEW.SCM and ICUNEW.TPL. These new files will contain
the completedefinition ofthe lCU, includingthe screensyoujust
defìnedfor your new driver. By namingthesefiles somethingother
than ICU286,you can presene the previousversionofthe ICU
files. HoweveÍ,to havethe new files take effectwhen the ICU is
run, you mustchangetheir namesto ICU286.SCMand
ICU286.TPL. For test purposes,you can changethe name of the
ICU executablefile to matchthe basenameofthe new file (e.g.,

rcuNEw).

DeviceDriversUset'sCuide

9-21

CONFIGURINC
A USER.WRITTEN
I)E!'ICEDRIVER

Onceyou finish addingsupportfor your driversto the ICU with the UDS and ICUMRG
utilities,you can configurethosedriversalmostasyou would any Intel-supplieddrivers.
Simplyinvoke the ICU and go to the "(UDDM) UDS DeviceDrivers Module." Enter the
appropri.te drìver t)'pe(T)errninrl or (C)onmon and the firll pathnamefor the location
of the objectcodefor your devicedriver. After you enter the correctvalue,choosethe
deviceyou want to configure. Then fill in the appropÍiatevalueswhen the ICU displays
the DeviceInformation,Unit Informaîion,and Device-Unitlnformation screens.

9.1.2.1UDSModules
Screenin theICU

(UDDM)
XoduIe*

I 1l

Driveì: iypè ,

Module*

You specify(C) for cornnon/random/customObject Module pathname(s)and (T) for
terminal drivers.
All driversaddedvia the UDS mustbe placedin modulesaccordingto typ€. All of your
termìnalmodulesmust be locatedin one module,all ofyour common/random/custom
driversmust be locatedin a separatemodule. For example,1 = T, TERMINAL.LIB and
2 = C. DRIVER.LIB

NOTE
Beforechanging
thenameof anyICUMRG outputfilesto ICU286.SCM
and
ICU286.TPL,
savethe orìginalfilesby copyìngthemto otherfiles(suchas
ICU286OLD.SCM
andICU286OLD.TPL).
AlthoughICUMRG allowsyouto add
supportfor newdrivers,onceyouaddthatsupport,thereis no wayto removeit. lf you
decideyoùdon'twantthe ICU to displayinformationaboutoneofyour drivers,or you
madea mistakewhenyouaddedthedriversupport,youmustrevertbackto the original
ICU28ó.SCM
andICU266.TPL
files(or an intermediate
versionthat didn'tcontain
supportfor thatdriver).

9.2 ADDINGYOURDRIVER
AS A CUSTOMDRIVER
If you don't want to modify the lCU, you can add your driver as a customdevicedriver.
Performthe followingstepsto do this:
1.

Ascertrin the delice numbersand device-unitnumbersto use in the DUIBS for
your devices,as follows:

DeviceDriversUsels Guide

CONFIGURING
A USER.WRTTTEN
DEI'ICEDRIVER

Use the ICU to configurea systemcontainingall the Intel-suppliedand ICUsupporteduserdriversyou require.
b. Usethe G option to generatethat system.
c. Use a text editor to examinethe file ?ICDEV.A28 (the ? meansthe first lerter can
vary). Among other things,this file containsDUIBS for all the device-unitsyou
defhed in your configuration.
d. Look for the TTDEVICETABLESmacrothat aDDears
after all the
DEFI\F-Dl llB stnrcturesThe secondand rhiià paramerers
in that macrolisl
are the next availabledevice-ùnitnumberand devicenumber,respectively.For
exdmple.
suppose
lhe qDEVICETABLES macroappearsas follows.
(NUMDUIB,
uDEVICETABLES
0000CH,
005H,003E8H)
In this case,the nexî availabledevice-unitnumberis oCH and the next available
devicenumber is 05H.
e. Use the next availabledevicenumberand device-unitnumberil your DUIBS.
2.

Crentethe following:
a. A file containingthe DUIBS for all the device-unitsyou are adding. Use the
DEFINE_DUIB structuresshownin ChaDter4. Placeall the structuresin the
samefile. Later, the ICU includesthis file in rhe assemblyof rhe ?ICDEV.A28
file.
b. A file containingall the deviceinformationtablesof the random/common/custom
type that you are adding. Use the RADEV-DEV_INFO structuresshownin
Chapter4 for any randomaccessdriversyou add. Use a structuresimilar to the
one shownin Chapter6 for terminaldrivers. Later, the ÌCU includesthis file in
the assemblyof the ?ICDEV.A28file.
c. If applicable,any random accessor commonunit informationtable(s). Use the
RADEV UNIT INFO strùcturesshownin Chaoter4 for anv random access
driver\you irdJ. Add lhcseldhle\to lhe [i]ecrearedin stepb.
d. l\ file containingall thc dcviceinformationrablesof the tern nal g?e that you ale
adding. Use the RADEV_DEV_INFOstructuresshownin Chapter4 ior any
random acc'ess
driversyou add. Use a structuresimilar to the one sho\r.nin
Chapter6 for terminal drivers. Later, the ICU includesthis file in the assemblyof
the ?lmEV.A28 file.
e. If applicable,any terminalunit informationtable(s). Use a structuresimilar to the
one shownin Chapter6 for terminal drivers. Add rhcscrablesto the file created
in stepb.
f.

Externaldeclararionsfor any proceduresthat you write. The namesof these
proceduresappearin either the DUIB or the DeviceInformation Table associated
with this dcvicedriver. Add rhcs€dcclaralionsro rhe file createdin srepb arld d.

DeviceDÌiversUsecsCuide

9-21

A USER.WRITTEN
DEI'ICEDRI!'ER
CONFIGURING

UsetheICU to configureyou. finalsystem.Whendoingso:
by the lCU.
a. Answer"yes"whenaskedifyou haveanydevicedriversnot supported
b. As input to the "Custom ljser Devicesnscreen, enter the pathname of your

random/common/customdevicedriver library. This refersto the library built
earlier:for example.
:F1:DRIVER.LIB.
c. As input to the "CustomUser Devices"screen,enter the pathnameofyour
terminal devicedriver library. This refersto the library built earlierj for cxamplc,
:FliTERMlNAL.LlB.
d. Also, enter the informationthe ICU needsto includeyour configurationdata in
the assemblyof ?ICDEV.A28 and ?ITDEV.A28. The informationneeded
irclurJesthe following:
.

DUIB sourcecodepathname(the file createdin step2a),

Deviceand Unit sourcecodepathnames(the files createdin steps2b through

Number of userdefineddevices.

Number of userdefìneddevice-units.

The ICU doesthe rest.
Figure 9-15containsan exampleof the "CustomUser Devices"scr€en.The bold text
representsuserinput to the ICU. In this example,the file :F1:DRMR.LIB containsthe
objectcodefor the random/common/customdrivers;the file :Fl:TERMINAL.LIB
containsthe objectcodefor the terminaldriver. F1:DUIB containsthe sourcecodefor
the DUIBS. and rF1:RINFO.INCcontainsthe sourcecodefor the Deviceand Unit
Information Tablesalongwith the necessaryexternalproceduredeclarationsfor the
random/common/customdrivers. TINFO.INC containsthe sourcecodefor the Device
and Unit Inlbrmation Tablesand the necessary
externalDroceduredeclarationsfor the
terminal driver.
The codein the DRM,R.LIB file supportsone devicewith two units. The code in
TERMINAL.LIB supportsone devicewith 2 units;therefore,the (ND) Numbe. oî User
Defined Devices[0-0FFH] field equals2, the (NEU) Number of User Defined DericeUnits [0-0FFH] field equals4. Refer to the ExtendediRMX II InteractiveConfiguration
Utility ReferenceManual for instructionson how to use the ICU.

9.24

DeviceD versUsefs Guide

CONFIGURINGA USER.WRITTENDEI'ICE DRII'ER

(USERD)
User Devices
(oPN)
RandomAccess object

Code PaÈh Nane [1-45 Chars/NONE]
NONE

(ToP)

Terninal

(oPN)

Duib Source codè Path Nane [1-45 CharsAoNE]

object

Code Path Nane [1-45 Chars/NoNE]
NONE

(DUP)
(TUP)
(ND)
(NDU)

NONE
chars/NONEI
NONE
Terninal Device and ùnit source Code Parh Name [1-45 CharsAoNE]
NONE
Nlnber of Useri Defíned Dewices [0-OFíH]
0H
Number of User Defined Devlce-Unirs [0-0FrH]
olt
RandomAccess Device and Unit

(N01)
(N04)
(N07)
(NIO)
(N13)
(N16)

(N02)
(N05)
(N08)
(N11)
(N14)
(N17)

NONE
NoNE
NONE
NONE
NONE
NoNE

NONE
NoNE
NoNE
NONE
NONE
NoNE

Source Code Parh Nane ft-4

(N03)
(N06)
(N09)
(N12)
(N15)
(N18)

NONE
NoNE
NONE
NONE
NONE
NoNE

O?N = |F1: DRMIi. LIB
ToP - : Fl:TERIINAL, LIB
OPN= :FÌ:DUIB- INC
T U P - r F l : T I N F O , I N C< C R >
ND - 2
NDU = 4

Figure9-15,ExampleUserDeric€sScrrrn

9.2.1 Example
of Addingan ExistingDriveras a CustomDriver
Thissectionillustrates
howto createthescreens
neededfor addingtheiSBC544A.device
to you $,stemusingthe UDS. Becausethe configurationof devicesin an iRMX systemis
complex,
thisexamplecovetstheprocess
in detail.

DeviceDriYersUser'sGuide

9.25

CONFIGURINGA USER-\IRITTEN DE!'ICE DRIItsR

Whilereadingthisexamplekeepin mindthatthecodefor terminaldriversis in a
differentsegment
thanthecodefor randomor commondrives.Because
of thissplitin
the segments,
caremustbe takento properlyprovidethecoÍect PUBLICS,EXTRNS,
andNOPUBLICSEXCEPT,andalsoto properlybindthecodesegments
together.

TOPwasleft at NONE in thisexample
because
the iSBC544Adrivercodeis alreadyin
thedriverlibraryXCMDRV.LIB. If youwereaddinganothermodule,youwouldenter
the locationof the file as a full path name.
OPN and DIIP were left at NONE bec:ìusethe driver beingconfiguredis a terminal
driver,not a randomaccess!
common,or customdriver.
You can add up to 18total Termhal DINFO and UINFO public namesin this screen.
9.2.1.1 Contentsof lhe OUtA.tNCfite specifíedin the (DpN) parameter
This s€ctionshovrsth€ contentsof the file ríhos€pathnaùe you suppliedin rhe (DPN)
DIIIB SourceCode Pathnameparameterof the User DevicesScreen.This assemblylAngùagefile providesthe informationneededto definehow the OperatingSystemshould
interfacewith this device.
Note the lines with arrowspointing to them. Theseare the devicenumberand device-unit
numberfor this device.Thesenumberswere takenfrom the ?ICDEV.A28 file as follows;

9-26

DeviceDriverc Usels Guide

CONFIGURINGA USER.ìIRITTEN DEVICEDRIVER

Ensurethat thc filcsyoustartwith containall of theIntel-suppJied
andICUsùpported
driversthatyourequire.Ifyou haven'tgenerated
sucha systemusethe
ICU to do sobeforecontinuing.

Usea texteditorto examinerhefile ?ICDEV.A28(the ? meansthat thefirstletter
canvary). Youwill find all of theDUIBSfor yourentiresystemin thisfile. Scan
thisfile for a line thatsrartswith %DEVICETABLE>

TTDEVICETABLE
is a mac.othatappears
belowall ofthe systems,
DEFINE_DUIBstructures.
Thesecondandthird parameters
in thatmacroarethe
nextavailable
device-unit
anddevicenumber,respeclively.
For example,
suppose
the %DEVICETABLEmac.oappearsasfollows:
(NUMDUÌB,
IDEVÍCETABI-E
0002EH,008H, 003E8H)

In thiscase,thenextavailable
device-unit
numberis 2EH andthenextavailable
device
numberis 08H.
4.

Usethesenumbersto fill in thetwolinesofthe file indicatedby thearrows.

At theendof thisfile areseveralmorelinesthatshouldbe noted.Be sureto examinethe
lastpart ofthis figureandreadthe textthatgoeswith it.

DeviceDriversUsefs Gùide

9-27

CONFIGURINGA USER.WRITTENDEVICEDRIWR

D E F I N E - D U I: far'
declarationfor eachDINFO and UINFO public namespecifiedheie. rhesenamesúust
be suppìiedas parametersN01 throughN18 above. This declarationis requiredbecause
all terminalinformationis storedin a different physicalsegnentthan other driver
information,and a far call is requiredto accessit.

9.2,1.2Contentsof the FileSpecifiedin the (TUP)Parameter
This sectionshowsthe contentsof the file whosepathnameyoùsuppliedin the (TUP)
Terminal Deviceand Unit SourceCodePath Name parameterof the User Devices
Screen.This assemblyJanguage
file providesthe informationneededto definehow the
OperatingSystemshouldinterfacewith this device.

9-30

DeYiceDrivers Uset'sGuide

CONFIGURING
A USER.WRITTEN
DEllCE DRII'ER

extrn I544FINISH : near
exth I544SETUP : near.
extrn I544CHECK: near
extrn I544ANSWER: near
exrrn I544HANGUP : near
extrn I544UTÌLITY : near
PUBLIC DTNFO-544A
DINFO_544A DIiI O4H
DW9
DW 300
Diì I5441N17
DiI T544FINISH
DW I544SETUP
DW TERMNULL
DW I544ANSWER
DW I544IÌANCUP
DW I544UTILITY
Di,I I
DI,TO71H
Dtrr t544CHECK
DD OFEOOOOH

Dr,i04000H
DB OIH
PUBLTCUINFO_544A
U1NFO.544A DW O1AH
DLÌ O1O9H
Dll 02580H
Dtr 00000H
Dtì 012H

Figure9-lt. PublicDeclarations
Needed
for the DINFOandUINFOTables

Providethe normal "extrn < MODULE NAME > : near',declarationsfor term$init. ....
term$linish
procedures.You musralso-provide
a PUBLTC.,labelpriorto
eachDINFO and UINFO rablespecified.

9.2.1.3Ponionof SystemcenerationSUBMTT
Fiteas Changedby this process
Aftercompleting
thechanges
outlined
above
youmustgenerate
a newsystem
usingthe
lCU. During the processof the systemgeneration,informationis sentto the screen-This
sectionpresentsthoseportionsof the systemgenerationthat are changedby the steps
outlined above.

Device Drivers UseÌrs cuide

9-31

CONFIGURING

A USER-WRITTEN

DEVICE DRIVER

BIOS

:UNG:ASM286
ICDEV.A28
ITDEV.A28 <.4)
: IANG:ASl,l286

: I,ANC:bnd286&
ITDEV.OBJ, &

r"_-ì earller
Ís now two files

releases

OF TSC CODE SEGMENT

LrB(xTsrF) , &
/Rroo86/ros/xcMDRV.
/RÌ.o{28 6/rOSIXCMDRV.LrB (XTSTO), &

86/ r0s/xcMDRv
. LrB, &
/RÌ,rx2

/RMX286/rOS/XDRWT . r-rB , &
: I,ANG
: PLM286.L]B, &
/RMX286/r,rBlRXXlrC . LlB &
( CODETO TSC_CODE,DATA TO TSC_DATA) &
RENAÌ"IESEC
(TSC.LNK)
OBJECT
NODEBUG
NOTYPESECSIZE(STACK(O)) &
NOLOADNOPUB]-ICS
EXCEPT(TSCINITIO, &
TSCFINISHIO, &
DINFO_o2H,&
urNFo_8251, &
DINFO-o3H, &
urNFo_18848, &
DINFO_o H, &
UINFO_546, &
urNfo_546cc, &
DINFO_o5H,&
UINFO-547A, &
DINFO_06H,&
UINFO_5478, &
DINFO O7H, &
UINFO_547C,&
DINFO_544A,&
USER SPECIFIED PUBLIC DINFO
UINFO_544A, &
U S E R S P E C l F l E D PUBLIC U]NFO
TSCQUEUEIO,
&

îsccANcELro)
rI,ANC:bnd286&
I O S 1 . ] - N K ,&
T S C . L N K ,&

INCLUSIONOF TSC SUBSYSTEM
IN IOS
SYSTEMBIND

Figure9-lt, Portion of the ModiffedSUBMIT File (.utinued)

9-32

DeviceDrivers User'sGuide

CONFIGURINC
A USER.WRIT'IEN
DEI'ICEDRI!'ER

ICDEV.OBJ, &
LlB, &
/Rl{x286lI0S/XCMDRV.
86II0S/XDRWT
. LtB , &
/Rì{X2
: IANCI PLM286.LIB, &
/RMX286/LrBlRMXlFC . LrB &
(TSC_DATATO DATA) &
RENAHESEG
OBJECT(TOS.LNK) NODEBUG
NOTYPESECSIZE(STACK(O)) &
N0LOADNOPUBLICSEXCEPT(rqaiosinitrask
, &
ReqAtlachDevice , &

Figure 9-lt. Pofion of the Modified SUBMIT File

Device Drivers Usefs cuide

933

In a MULTIBUS I systeminterrupt-drivendevic€scan be either devicesatracheddir€ctly
to the CPU board or separatecontrollers.In MULTIBUS ll systemsthesedevicesmust
be attacheddirectlyto the CPU board. Interrupt,drivendevicessignalthc CPU hostvia
interruptsat a specifiedinterrupt level.
This appendirdescribes,in generalterms,the operationsof the random accesssupport
routinesas they applyto interrupt-drivendevices.The routinesdescribedinclude
INTNIO
FIMSH$IO
QUEUE$IO
CANCEI]iIO
INTERRUPT$TASK
Theseroutinesare suppliedwith the I/O Systemand are the devicedriver routines
actuallycalledwhen an applÌcationtask makesan I/O requestto supporta randomaccess
o. commondevice. Theseroutinesultimatelycall the device-specific
deviceinitialize,
devicefinish, devicestart,devicestop,and deviceinterrupt procedures.
This appendi,(providesdescriptionsof theseroutinesto showyoll the stepsthat an actual
devicedriver follows. You can uselhis appendixto get a better understandingof the l/O
System-supplied
portion of a devicedriver to makewritilg the device-dependent
portion
easicr. Or you can useit as a guidelinefor writing customdevicedrivers.

4.1 INIT$IO
PROCEDURE
The I/O SystemcallsIMT$IO when an applicationtask makesan
RQ$A$PHYSICAL$ATTACH$DEVICE svstemcall and no units of the devicearc
currentlyattached.
IMT$IO initializesobjectsusedby the remainderofthe driver routires, createsan
ìnterrupt task,and callsa user-supplied
procedureto initializethe deviceitseli

Device Drivers Usefs Grìide

A I

RA\IDOM ACCESSSUPPORT FOR INTERRUPT-DRTVENDE\,'ICES

Whenthe I/O SystemcallsIMT$IO, it passes
thefollowingparameters:
.

A pointer to the DUIB of the device-unitto inirialie

A pointer to the locationwhereINIT$ÌO mustreturn a token for a datasegnent
(datasto.agea.ea)thatit creates

A pointerto thelocationwhereINIT$IOmustreturntheconditionmde

The followingparagraphsshowlhe generalstepsthe IMT$IO procedurefollowsto
initialize the device. FigureA- l illustratesthesesteps.The numbemin the ligure
corresoond
to the st€onumbcrsin thc text.

DeviceDrivers Uset's Guide

RANDOMACCESSSUPPORTFOR INTERRUPT-DRIVENDEVICES

o
ot----------r
****^t

FigureA-1. RardomAccessDeviceDriver Initialize I/O Procedule

Device D vels Uset's Guide

A-3

MNDOM ACCESSSI]PPORTFORINTERRUPI.DRII'ENDEI'ICES

It createsa datastorageareato be usedby all theprocedures
in the devicedriver.
The sìzeófthis areadepends
in part on thenumberof unitsin the deviceandany
specialspacerequirements
ofthe device.INIT$IOthenbeginsinitializingthisarea
and eventuallyplacesthe followinginformationthere:
.

A token for a region. Step2 createsthis regionfor mutual exclusion.
An array !o conlainlhe addresses
of the DUIBS for the
device-unitsattachedto this device. lNlT$IO placesthe
addressof the DUIB for the first attachingd€viceunit into
this array.
A token for the interrupt task.
Other valuesindicatingthe queueis emptyand the driver
is not busy.

It alsoreseruesspacein the data storageareafor devicedata.
2.

It createsa region. The other randomaccesssupportroutinesreceivecontrol of
this regionwhenevertheyplacea requeston the queueor removea requestftom
the queue. IMT$IO placesîhe token for this regionin the data storagearea.

It entersthe regionto preventthe interrupt task from startingbeforeinitialization
ìs complete.

It createsan interrupt task to handleinterruptsteneratedby this dcvicc. Whcn
INI'ISIO hvokes CREATE$TASK to createthe interrupt task,it doesnot speciry
the task'sdata segment.Instead,it usesthe data$segparameterof
CREATE$TASK to passthe interrupt task a token for the data storagearea. This
area is wherethe interrupt taskwill get informationaboutthe device. INII$IO
placesthe actualdata segmentvalue,aswell as a token for the interrupt task,in the
oata storageafea.

It callsa device-sperificdeviceìnitializationprocedurethat initialìzesthe device
itself. It getsthe addressof this procedureby oemining the DeviceInformation
Tablespecifiedin the DUIB. Refer to Chapter5 for informationon how to write
this initializationprocedure.

It €xitsthe region.

lt returnscontrol to the l/O System,passinga token for the data storageareaand a
conditioncodewhich indicatesthe success
of the iltitializationoperation.

If an error occursat any point in thesesteps,the lNIfilO procedureexitsthe region,
deletesaII the objectsit hascreatedup to that point, and returnsan error to the I/O
Svstem.

DeviceDriversUseCsGuide

RANDOMACCESSSUPPORT
FORINTERRUPT.DRIVEN
DEVICES

4.2 FINISH$IO
PBOCEDURE
Thel/O SystemcellsFINISH$IOwhenan application
taskmakesan
RQ$A$PHYSICAUDETACH$DE\,ICE
systemcallandno orherunitsofthe deviceare
currentlyattached.
FIMSH$IOcallsa user-supplied
procedure
to perlormfinalprocessing
on the device
itself,deletesthe ìnterrupttask,anddeletesobjectsusedby the otherdevicedriver
routines.
Wlen theI/O SystemcallsFIMSH$IO,it passes
thefollowingparametersl
. A pointerto the DUIB of thedevice-unitjust
detached
.

A TOKENfor thedatastorageareacreatedby IMT$IO

Thefollowilgparagraphs
showthegeneralstepsthattheFINISH$IOprocedure
goes
throughto terminateprocessing
for a device.FigureA-2 illustrates
thesesteps.The
numbersin thefigurecorrespond
to the stepnumbersin thetext.
1. It callsa device-specific
devicefinishprocedutethatperformsanynecessary
final
processing
on the deviceitself. FINISH$IOgetsthe address
of thisprocedure
by
examining
the DeviceInformationTablespecified
Ìn the DUIB. Referto the
Chapter5 for informationaboutdeviceinformationtables.
2.

It deletestheinterrupttaskoriginallycreatedfor the deviceby rheINIT$IO
procedure
andcancels
the assignment
ofthe jnterrupthandlerto the sperified
interruptlevel.

It dclctcsthc rcgionandthe datastorageareaoriginallycreatedby rheINIT$IO
procedure,
allowingtheoperatingsystemto reallocate
the memoryusedby these
oDlects.

It returnscontrolto the I/O System.

DeviceDriversUser'sGuide

A-5

RANDOMACCESSSUPPORT
FORINTERRUPT.DRI!'EN
DE!'ICES

FINISHSIO
C A L L SU S E R . S U P P T I E D
P R O C E O U F fÈO F I N I S HU P
PPOCESSING
ONTHFDEVICE

D E L E T E SI N T E R R U PI' A
TSK FOR
D E V I C EA N D R E S E T SI N - T E R R U P T

D E I € Ì E S R E G I O NA N O D A Ì A O B J E C I S
U S E DB Y I H I S O E V I C ED f i I V E R

F E ' I U F N ST O T H E I / O S Y S I E M

1476

figure A-2. RandomAccessDeviceDriver Finish l/O Procedùre

A,3 QUEUE$IO
PROCEDURE
The I/O Systemcallsthe QUEUE$IO procedureto placean l/O requeston a queueof
requests.This queuehasthe structureofthe doublylinkedlist shownin Figure 7-1. If
the deviceitself is not busy,QUEIIE$TO alsostsrtsthe request.

A-t

DeviceDriversUset'sGuide

RANDOMACCESSSUPPORTFOR INTERRUPT.DRIWN DE\{CES

Whenthe I/O Systemcals QUEUESIO,it passcs
thc follov/irig
paramete$:
.

A tokenfor theIORS

A pointerto the DUIB

A tokenfor thedatasrorage
areaodginalycreatedby INIT$IO

The followingparagraphs
showthegeneralstepsthat theQUEUESIOprocedure
gocs
throughto placea requeston the I/O queue.FigureA-3 illustrates
thesesteps.The
numbersin the figurecorrespond
to thestepnumhersin the text1.

It setstheDONE fi€ldin theIORSto 0H, indicatingthe requesthasnot yetbeen
mmpletelyprocessed.
Otherproceduros
tlìatstalt the I/O rransfcrs
andhandle
interruptprocessing
alsoexamineandsetthisfield. It alsosetsIORS.STATUS
to
E$OKand IORSACI-UALto 0H.

It receives
controlof theregionandthusaccess
to the queùe.Thisallows
QUEUE$IOto adjustthe queuewithou!concernîhatothertasksmightalsob€
doingthisat the sametime.

It verifiesthat therequestis withintherangeof zeroto devicesizefor thisdevice.
lf the requestis outsidethisrange,QUEUE$IOrerurnsE$PARAM. For a valid
.equest,it convertsIORS.DEVIiLOC
trom theabsolute
bytepositionon the device,
aspassed
by the BIOS,to the absolute
block(sector)number(if tracksizeequals
zero). Ifthe tracksizeis not zeroIORS.DEVgLOC
is converted
to the seqorano
tracknumber.Finally,it placesthe IORSon thequeuein seek-optimized
order.

Ifthe deviceis busyprocessing
an I/O request,QUEUE$IOgoeson to Step5.
Otherwise,
it callsthe device-specific
devicestartprocedureto process
the request
ar the headof the queue.Thisstartptocedureis described
in Chapter5.

It surrenders
controlof theregion,thusallowingotherroutinesto haveaccess
to
thequeue.

NOTE
If the requestis complete,
QUEUE$IOretùrnstheIORSto theresponse
mailbox;ifnot, the interrupttaskreturnsit uponcompletion.The random
access
supportdoesnot returna CLOSErequestuntil all prior requests
for thesameunitarecoúpleted.

DeviceDriversUser'sGuide

A-7

MNDOM ACCESSSUPPORT
FORINTERRUPT.DRII'EN
DE\ICES

AUEUE$IO
SETSSÍAIUS F ELDS
IN fHE IOFS

GA NS ACCESS
ÎO IHE FEG1ON

PLACESIHE OFS
ON IHE OUEUE

SIAB TS ÌBE PAOCESSNG OF fIJE
REQUES-IIF IHE DEVCE S NO-I BUSY

S U R B E N D ÉARCSC E S S
rO ÌF]E FEG]ON

RE'TUBNS
IO IHE l/O SYSTEM

Figure A-3. RandomAccessDeyiceDriver QueueI/O Procedure

4.4 CANCEL$IOPROCEDURE
The I/O SystemcallsCANCEL$IO to removeone or more reqùestsfrom the queueand
possiblyto sîop the processingof a request,il it hasalreadybeenstarted. The l/O System
callsthis procedurein one of two instances:

A-8

DeviceDrivers Usey'sGuide

RANDOMACCESSSUPPORT
FORINTERRUPT.DRIVEN
DEITCES

lf a taskinvok€sthe RQ$A$PHYSICAIJDETACH$DEVICE
sysrem
calland
specifiesthe hard detachoption (refer to the Erîended\RMXII BaticI/O SystemCaIs
manualfor informationaboutthissystcmcall). The harddetachremovesall requests
from the queue.

If lhejob containing
the taskthatmakesan I/O requestis deleted.In thiscase,the
I/O SystemcallsCANCEUIO to removeall ofthat task'srequesrs
from the queue.

WhentheI/O SystemcallsCANCEI]$IO,it passes
thefollowingparameters:
. An ID valuethat identifiesrequests
to becanceled
.

A pointerto theDUIB

A tokenfoathe devicedatastoragearea

Thefollowingparagraphs
showthegeneralstepstharthe CANCEL$IOprocedure
goes
throughto cancelan I/O request.FigureA-4 illustrates
thesesteps.Thenurnbers
in the
figurecorrespond
to thestepnumbersin thetext.
l

It receives accessto the queue by gaining control of the region. This allows ir to
remove requests from the queue without concern that other tasks mìght also be

processingthe IORS at the sametrme.
2.

It locatesthe request(s)to be canceledby looking at rhe cancel$idfield ofrhe
queucdIORSS,startingat the front of the queu€.

If the requestthat is to be canceledis at the headof the queìle,that is, rhe deviceis
processingthe reqùest,CANCEL$lO callsa device-specific
devicestopprocedure
that stopsthe devicefrom further processing.Refer to the Chapter5 for
informationon how to write this devicesropprocedure.

If the requestis finished,or ifthe IORS is nor at rhe head of the queue,
CANCET$IO removesthe IORS from the queueand sendsit to the resoonse
mailboxindicatedin the IORS. Itexaminestherestoftherequesrs
on t-hequeu€,
removingall ofthem whosecancelgidfieldsmatchthe lD oi the canceledrequesî.

It surrenderscontrol ofthe region,thus allowingother proceduresto gain accessto
the queue.

NOTE
The additionalCLOSErequestsuppliedby theI/O System
will not be
processed
until all otherrequests
with thegivencancelgid
valuehavebeen
dealtwith.

DeviceDriversUserjsGuide

A-9

RANDOMACCESSSUPPORT
FORINTTRRUPT-DRIYEN
DE\TCES

^.1110

FtgureA-4. RaúdomAccessDeviceDriver CancelI/0 Procedure

A-10

DevlceDriYersUset's Guide

RANDOMACCESSSUPPORTFOR INTERR.UPî-DRII'ENDEITCES

4.5 INTERRUPT
TASK(INTERRUPT$TASK)
As a part ofits processirg,
theIMTgIO procedure
createsan internìp!taskfor lhe entire
device.Thisinterrupttaskresponds
to all interuptsgenerated
by the unitsof the device,
processes
thoseinterrupts,andstartsth€ deviceworkingon thc nextI/O r€questoDthe
queue.
The followingparagraphs
showthegeneralstepsthatthe interrupttaskfor therandom
accessdevicedriver goesthroughto processa deviceinterrupt. FigureA-5 illustrates
thesesteps,The numbersin FigureA-5 correspond
to the stepnumbersin thetext.
1. It usesthe contentsofthe processor's
DSregisterto obtaina token(identifier)for
the devicedatasto.agearea. This is possiblebecaùseof the followingtwo teasons:
. WhenIMT$IO createdlhe imerrupatask,insteadof specirying
the
interrupttask'sDSregisterin thedata$seg
parameterof the
CREATE$TASK
ca[, it passed
the tokenofthe datastoraS€
ar€aiî rhis
parameter.Therefore,
whentheNucleuscreatedthe task,it setthetask's
DS registerto thevalueof thetoken.
r WhentheIMT$IO procedure
initialìzedthe datastoragearea,it
includedthc valucof theÌnterrupttask'sDSregisterthere.
Whentheinterrupttaskstarîsrunning,it savesthecontentsof theDS register(to
useastheaddress
of thedatastoragearea)andsetsthe DS registerto thevalue
listedin the datastoragearea.Thusthc DSregisterdoespointro rhetask'sdata
segment,
andthe taskalsoknowstheaddress
of the datastoragearea.Thisis th€
mechanism
thatis usedto passthe address
ofthe device's
datastotageareafrom
the INIT$IOprocedur€
ro rheinl€rrupttask.
2.

It invokesthe RQ$SET$INTERRUPI
systemcallto indicatethatit is an inrerrupt
taskassociated
with theinterrupthandlersuppliedwith the randomaccess
device
driver.lt alsoindicates
the interruptlevelto whichit will respond(ir obtainsthis
informationfrom rheDeviceInformationTable).

lt b€ginsan infiniteloopby invokingthe RQE$TIMED$INTERRUPT
systemcall
to waitfor an inter.uptof the specified
level.If thetime limit erpiresbeforean
interupt occurs,theeffectis thesameasa null (or spurious)interrupt,andthe task
waitsfor anotherinter.upt.By invokinga nunberof RQE$TIMED$INTERRUPT
calls,insteadof a singleWAIT$INTERRUPT,
rhetaskallowslower-priority
tasks
to gaincontrolbetween
calls.For example,
if an application
attemptsto senddata
to a lineprinterthatisn'tconnected,
theusercanpressCONTROL-Cto cancelthe
operation.

DeviceDrivers Us€t's cùide

^-tl

LA,NDOM À,CCESSSUPPORT FOR INTERRUPT.DRI!'EN DE\,'ICES

Figùre A-5. Random AccesgDevice Driver Interrupt Tosk

A-12

DeviceDrive$ Usels Guide

RANDOMACCESSSUPPORT
FORINTERRUPT-DRII'EN
DEI'ICES

Via a region,it gainsaccess
to therequestqueue.Thisallowsit to examinethefirst
entryin the requestqueuewithoutconcernthatothertasksaremodiryingit at the
sametime-

It callsa device-specific
device,interrupt
procedure
to process
the actualinterupt.
This caninvolveverifyingthat the interrupt waslegitimateor anyother operation
that the devicerequires. This interrupt procedureis describedfurther in
Chapter5.

ó.

lf therequesthasbeencompletely
processed,
(onerequestcanrequiremultiple
readsor writes,for example),
the interrupttaskremoves
the IORSfrom thequeue
andsendsit asa message
to the response
mailbox(exchange)
indicatedin the
IORS. If the reque$tis not completely
processed,
the interrupttaskleavesthe
IORSat the headofthe queue.

Ifthere are requests
on the queue,the inter.upttaskinitiatestheprocessing
of the
nextl/O requestbycallingthe device-specific
procedure.
device-start
ln anycase,the interrupttaskth€nsurrendets
access
to the queue,allowingother
routinesto modirythequeue,andloopsbackto waitfor anotherinterrupt.

Device Drivers Userrs cuid€

A-t3

In an interrupt-driven
system,
the CPUhostandthecontrollercommunjcate
via hardware
interrupts.In systems
havingfull message-passing
capabilìties,
thiscommunicaîion
is
donevia vitual interrupts(moreprecisely
notedasmessag€s
throughout
thisappendix).
For an ov€rviewandexamples
ofthe message-passing
process,
seetheExtended
\RMXII
NucleusUser'sGuíde.
Thisappendixdescribes,
in generalterms,theoperations
of the randomaccess
support
routinesastheyapplyto message-passing
devices.Theroutinesdescribed
include
IMT$IO
FIMSH$IO
QUEUE$IO
CANCEL$IO
MESSAGE$TASK
Theseroutinesaresuppliedwith the l/O Systemandare thedevicedriverroutines
actuallycalledwhenan application
taskmakesan I/O requestto supporta randomaccess
or commondevice.Theseroutinesultimatelycallthedevice-specific
deviceinitialize,
devicefinish,devicestart,devicestop,anddeviceinterruptprocedures.
Thisappcndixprovidesdescriptions
of theseroùtinesto showyouthe stepsthatan actual
devicedriverfollows.You canusethisappendi\to gera betterunderstanding
of theI/O
System-supplied
portionof a devicedriverto makewritingthedevice-dependent
portion
easier.Or youcanuseit asa guidelinefor writingcustomdevicedrivers.

8.1 INIT$IO
PROCEDURE
TheI/O SystemcallsINIT$IOwhenan application
taskmakesan
RQ$A$PHYSICAf$ATTACH$DEVICE
systemcallandno unitsof the deviceare
currentlyattached.
INIT$IO initializesobjectsusedby the remainderof thedriverroutines,createsa
message
procedure
task,andcallsa user-supplied
to initializethe deviceitself.
Wlen the I/O SystemcallsINIT$IO,it passes
thefollowingparameters:
.

A pointerto theDUIB of the device-unit
to initialize

DeviceDriv€rs Useis Cuide

B-l

RANDOM ACCESS SIIPPORT FOR MESSACE-PASSING DEVICES

A pointerto the locationwhereINIT$IOmustreturna tokenfor a datasegment
(datastoragearea)that it creates

A pointerto the locationwhereINIT$IOmustretumtheconditioncode

The followingparagraphsshowthe generalstepsthe IMT$IO procedurefollowsto
initializethedevice.FigùreB-1illustrates
thesesteps.Thenumbersin the figure
correspond
to the stepnumbersin thetext.

rNrT$ro
C F É A -ETS T H E O B J E C f F O R
O E V I C ÉA N D S I A F I S F I L L I N GI I

C R E A T E Sf H E R E G I O NF O A
A A C E S SI O I H E Q U E U E

E N fE F S T H E B E G I O N

CFÈA-E
TS IHE
I N TE R N UP T l M E SS A GÉ
IASK

U S E F . S U P P L I EPOF O C E D U R E

r o t Nt Tt a Lr zE o E v t cÉ

AEGION

a E f u F N sT o t / o S Y S T E M

PASSINGOAIA OBJECI AND

rNco0É
c o ND r -t o

w-0311

FigureB-1. RandomAccess
DeviceDriverInitiatizeI/O prucedule

B-2

DeviceDrivers Usefs Guide

RANDOMACCESSSUPPORT
FORMESSAGE.PASSING
DEI'ICES

It caeatesa dala storageareato b€ usedby all the proceduresin the devicedriver.
The sizeoîthis areadependsin part on the numberof units in the deviceand any
specialspacerequifem€ntsof the device. INIT$IO then beginsinilializing rhis area
and eventuallyplacesthe followinginformationthere:
.

A token fo. a region. Step2 createsthis regionfor mutual exclusion.

An array to containthe addresses
ofthe DUIBS for the
device-unitsattachedto this device. INIT$IO olacesthe
addrersof rhe DUIB for rhefirst atrachins
deviceunit into
this array.

A token for the messagetask.

Other valuesindicatingthe queueis emptyand the driver
ls noaDusy,

A port objectusedby the messagetask to receive
messages
from the controller. The user-supplicddrivcr uses
rhis object to sendmessages
to the controllei.

It alsoresewesspacein the datastoragearea for devicedata.

It createsa region. The other randomaccesssuppoatroutinesreceivecontrol of
this regionwheneverthey placea requestod the queueor removea requestfrom
the queue. IMT$IO placesthe token for this regionin the data storagearea.

It entersthe regionto preventthe messagetask from startingbeforeinitializatÌonis
complete.
It callsa device-specific
deviceinitjalizationprocedurethat initializesthe device
itself. It getsthe addressof this procedureby examiningthe DeviceInformation
Table spe.ifiedin the DUIB. Refer to Chapter5 for informationon how to write
this initializationprocedure.

It createsa messagetask to handlemessages
generatedby this device. When
IMT$IO invokesCREATE$TASK to createthe messagerask,it docsnot spcciry
the task'sdata segrent. Instead,it usesthe data$segparameterof
CREATE$TASK to passthe messagetask a token for the data storagearea. This
area is wherethe messagetaskwill get informationaboutthe device. INIT$IO
placesthe actualdatasegmentvalue,aswell as a token for the messagetask,in th€
data storaEearea.

DeviceDrivers UserrsGuide

R-3

RANDOMACCESSSUPPORT
FORMESSAGE.PASSING
DEVICES

It exitsthe region.

It returnscontrolto the I/O System,
passing
a tokenfor the datastorageareaanda
conditioncodewhichindicates
the success
ofthe initializationoperatio[.

If an error occursat anypointin thesesteps,theIN{T$IOp.ocedureexitsthe region,
deletesall the objectsit hascreatedup to thatpoint,andretumsan errorto the I/O
System.

8.2 FINISH$IO
PROCEDURE
The I/O SystemcallsFINISH$IO when an applicationtask makesan
RQ$A$PHYSICAI$DETACH$DEVICE svstemcall and no other units of the deviceare
currentÌyattached.
FINISH$IO callsa user-supplied
procedureto perform final processingon the device,
deletesth€ messagetaik, and deletesthe objectsusedby the other devicedriver roufines.
When the I/O SystemcallsFINISH$IO, it passesrhe followingparameters:
.

A pointer to the DUIB of the device-unitjust detached

A TOKEN for the data storageareaqeated by INIT$IO

The followingparagraphsshowthe generalstepsthe FINISH$IO procedurefollowsto
terminateprocessingfor a device.Figure B-2 illustratesthesesteps.The numbersin the
figure correspondto the stepnunrbeisin the text.

B-4

It callsa device-specific
devicefinishprocedurethat performsany necessaryfinal
processingon the deviceitself. FINISH$IO getsthe addressof this procedureby
examiningthe DeviceInformationTable specifiedin rhe DUIB. Refe. to Chaprer5
for informationaboutdeviceinformariontables.

It deletesthe messagetask originallycreatedfor the deviceby the INIIT$IO
proceduae.

It deletesthe regionand the data storageareaoriginallycreatedby rhe INIfiIO
procedure,aÌlowingthe OperatingSystemto reallocatethe memoryusedby these
ooJects.

lt returnscontrol to the I/O System.

D€viceDrivers UserrsGuide

MNDOM ACCESSSUPPORT
FORMESSAGE-PASSING
DEVICES

F NtSH$tO
C A L L SU S E R S U P P L I E D
P q O C E D U B TE O F I N i S HU P
PROCESSING
O N T H E OE V I CE

D E L E TE S M E S S A G E
T A S K F O R D E V I CE

D E L E T E SR E G I O NA N D O A I A O B J E C I S
U S E D B Y T H S D E V I C ED R I V E R

F É I U R N SI O T H E I / O S Y S T E M

FigureB-2. RandomAccessDeviceDriver Finlsh I/O Procedure

8.3 QUEUE$IO
PROCEDUHE
For message-passing
devices,
the I/O Systemcallsthe QUEUE$IOprocedure
to placean
I/O rcqueston a queueof requests
on a first-in-first-out
basis.Thisquer-re
hasthe
structureofthe doubly-linked
list shownin Figure7-1. Thisprocedurecallsa usersuppliedprocedure
to startprocessing
theI/O requests.

DeviceDrive$ UserrsGùide

B-5

MNDOM ACCESS
TORMESSACE-PASSINC
DEvICES
SUPPORT

When the I/o SystemcallsQUEUE$IO, it passesthe followingparameters:
.

A token for the IORS

A pointer to the DUIB

A token for the data storagearea originallyc'eated by INIT$IO

The followingparagaphs showthe generalstepsthe QUEUE$IO proceduregoesthrough
to placea requeston the I/O queue. Figure B 3 illustratesthes. steps. The numbersin
the figure correspondto the step numbersin the îext.
1.

It setsthe DONE field in the IORS to 0H, indicatingtne requesthasnof yet been
completelyprocessed.Other procedu.esthat start lhe I/O transfersand provide
mcssagchandlingalsocxamincand set this field. It alsosetsIORS.STATUSto
E$OK aùd IORS.ACTUAL to 0H.

It receivescontrol of the regionand thusaccessto the queue. Ihis allows
QUEUE$IO to adjustthe queuewithout concernthat other tasksmight alsobe
doing this at the samelime.

lt verifiesthat the requestis within the rangeof zero to devicesizefor this device.
If the requestis outsidethìs range,QUEUE$IO returnsE$PARAM. Then it places
the IORS on the queue.

devicestart procedureto processthe request
QUEUE$IO callsthe device-specific
at the head of the queue. This start procedureis describedin Chapter5.

It surrenderscontrol of the region,thusallowingother routinesto haveaccessto
the queue.

lt retuÍnscontrol to the I/O Svstenr.

NOTT
If therequestis complete,
QUEUE$IOreturnstheIORSto the response
mailbox;ifnot, themessage
taskreturnsit uponcompletion.lhe random
access
supportdoesnot returna CLOSErequestuntil all prior requests
for lhe sameunitarecompleted.

B-6

Devic€DriversUser'sCuide

RANDOMACCESSSUPPORT
FORMESSAGE-PASSING
DEVICES

OUEUE$IO
S E -S
T S T A TU S F I E L O S
T H EI O B S

G A I N SA C C E S ST O ' T H E
REGION

P L A C E ST H E I O F S I N
.THE
QUEUE

S I A R f S P R O C E S S I N GI H E
REQUEST

S U R B E N D E RA
S C C E S Sf O - T H E
REGION

R E Ì U R N SI O I H É
S Y S TEM

w-0313

FigureB-3. RandoríAccessDeviceDriver QueùeI/O Procedure

8.4 CANCEL$IOPROCEDURE
This procedureperformsno operationsfor message-passing
devices.The messagetask
sweepsthroughthe requestqueueand startsall requests.Becauseof this feature,all I/O
requestsare guaranteedto finishwithin a limited time.

DeviceDriversUsefsGuide

RANI)OMACCESSSUPPORT
FORMESSAGE.PASSING
DEYICES

NOTE
The CLOSErequestsuppliedby the I/O Systemis immediately
sentto the
user-supplied
devicestartprocedure.However,therandomaccess
supportdoesnot returnit to the I/O Systemuntil all requests
in the queue
havebeencompleted.

8.5 MESSAGETASK(MESSAGE$TASIO
The IMT$IO procedurecreatesa messagetask for the entir€ device This messagetask
respondsto all messages
generatedby the units of the device,processesthosemessages,
and startsthe deviceworking on the unstartedI/O requestson the queue.
The followingparagraphsshowthe generalstepsthe messagetask for îhe random access
devicedriver followsto processa messageliom the device. Figùre B-4 illustratesthese
steps. The numbersin Figure B-4 correspondto the stepnumbersin the text.
1.

lt usesthe contentsof the processor'sDS registerto obtain a token (identifier) for
the devicedata sîoragearea. This is possiblefor thesereasons:
. When INIT$IO createdthe messagetask,insreadof speciryingthe
messagetask'sDS registerin the data$segparameterof the
CREATE$TASK ca[, it passedthe token of the data storagearea in this
parameter. Therefore,when the NucÌeuscreatedthe task,it set the task's
DS registerto the valueof the token.
. When the TNIT$IOprocedùreinitializedrhe data storagearea,it
includedthe valueofthe messagetask'sDS registerthere.
When the messagetask startsrùnning,it savesthe conlentsoI the DS register(to
use as the addressof the data storagearea)and setsthe DS regist€.to the value
listed in the data storagearea. Thus the DS registerdoespoint to the task'sdata
segment,and the task alsoknowsthe addressof the data storagearea. This is the
mechanismusedto passthe addressof the derr';ce's
dàta storag€areafrom the
INIT$IO procedureîo the messagetask.

B-8

It bcginsan ìnfinite loop by invokingthe RQ$SEND$RS\? catl ro wai! at lhc porr
for messages
from the device. For more informationon how to sendand receile
messages
to/from specificports,seethe descriptionof the Nucleus
Communications Service inthe Efie ded .RMX II Nucleus Ilser's Guídc. For setting
the messagetask priority, seethe descripîionofthe "NucleusCommunications"
s$eeù in the Extended|RMX II Intemctive Cohfrgumtían Utíli, Refercrcemanual.

Via a rcgion,it gainsaccessto the requestqueue. This allowsit to €xantinethe first
entry in the requestqueuewìthout concernthat other tasksare modilyingit at the

It callsa user-writtendevice-inîerruptprocedureto processthe receivedmessage_
This irìterruptproccdureis describedfurther in Chapter5.

DeviceDriversUse/s Cuide

RANDOMACCESSSUPPORT
FORMESSAGE.PASSING
DEVICES

The message
taskcheck the statusof thenextrequestin the queue.

ó.

Ifthe requesthasbeencompletely
processed,
(onerequestcanrequiremultiple
readsor writes,for example),
themessage
taskremovestheIORSfrom the queue
andsendsit asa message
to the.esponse
mailbox(exchange)
indicatedin the
IORS. If therequestis not completely
processed,
themessage
taskleavestheIORS
in thequeuebut checksto seeif thereqùesthasbeenstarted.

lf therequesthasnot beenstarted,themessage
taskcallstheuser-supplied
device
procedure
staat
to paocess
therequest.

In anycase,themessage
taskthensuarenders
access
to the queue,allowingother
routinesto modirythe queue,andloopsbackto waitfor anothermessege
from the
controller.

DeviceDriversUse/s Guid€

B-9

RANDOM ACCESSSUPPORTFOR MESSACÌ].PASSINGDEVICES

MESSAGE$fASK
G E T S S E L E C T O RF O 8 D E V I C ED A T A
S T OR A GE A R E A F R O M O S F E G I S T E R

W A I I S F O R M E S S A G EA I
S P E C I F I E DP O R - T

fHE

G A I N SA C C E S ST O B E G I O N

C A L L SI H E U S E R . W R I I I E I\ N I E F F I J P ]
P R O C E D U Rf EO P R O C E S S
THEMESSAGE

GFf IORSFROMf HE OUEUE

e
o

o
ES

'THE
E M O V E ST H E I O R S F R O M
E U E A N O S E N D SA I ' I E S S A G E
Ìo
f H E F E S P O N S EÀ 4 4L B O X

"X
ts

IHE FEOUEST
S-TAR-TEO?

NO
C A LL T H E U S E R , W S ] T T E N
D E V I CE S I A N - TP R O C E D U R E
T O S TA R T T I I E R E O U E S T

S U B B E N D EA
RC
S C E S S ' T O ' TBHEEG I O N

FigureB-4. RandomAccess
DeviceDÌiverMessage
Task

B-10

DeYiceDrivers U$efs Guide

For compatibility
with ECMA (European
ComputerManùfacturers
Association)
andISO
(International
Organization
for Standardization),
theIntel-supplied
devicedriverscan
formatthebeginning
tracksof all flexiblediskettes
in thesamemanne.,regardless
of the
formatof theremainderof thediskette.Thisformattinsis referredto asstanda.d
formatting.The otheroption,in whichall rracksof a diikertehavethesameformat,is
referredto asuniformformatting.
The standardformaningfor cylinder0 on flexiblediskettes
is asfollows:
For5-1l4"diskettes
. Cylinder0, side0 is formattedwith 128-byte
sectors,
singledensiry,16sectors
per
îrack.
. If the disketteis double-sided,
cylinder0, side1 is formattedlike the resrofîhe
t.ackson thediskette.
For 6' diskertes
o Cllinder0, side0 is formattedwith 128-byte
sectors,
singledensity,26sectorsper
track,
. If thedisketteis double-sidecl,
cylinder0, side1 is formattedwith 256-byte
sectors,
doubledensity.26 sectors
per track.
The FIAGS field in a device's
DUIB indicates
whetherthat deviceexpects
(reads,writes,
andformats)diskettes
in standardor uniformformat.
To beconsistent
with theIntel-supplied
drivers,andto be ableto correctlyaccess
standardformatdiskettes
from othersystems,
randomacccss
diskcttedriversthatyou
writemustbe ableto read,write,andformatdiskettes
in thisstandardformat.
To access
standard-formaited
diskeîtes,
a devicedrivermustbe ableto translatea logical
blocknumber(assuppliedto it in rheDEV$LOCfield of theIORSby the I/O System)
into a physicaladdress
(cylinder,head,andsector).It musttakeinto consideration
that
track0 mightbeformatteddifferentlythantherestof the diskette,andthatrheremight
be a differentmrmberof losicalblockson track0.

DeviceDriversUser,sGuide

c-r

SIIPPORTING
THE STANDARD
DISKETTEFORMAT

The following algorithm can be used to calculate the physical address for 5-1/4" fl€xible
diskette requests. It assumesthe program has accessto th€ IORS and the DUIB. A
similar algorithm can be used for 8" diskettes. (Remember, the algorithm for 8" diskettes
must also take into account the special formatting of cylinder 0, side 1 on double-sided
diskettes.)

/*
*
*

Calculate the nll]nber of logtcal
blocks
track 0 usin8 the standard granularity
per track.

on che standard - forr0atted
and standard nunber of sectors

(128 bytes/sector x 16 sectors/track)
track-0-blocks =
( device - granular i ty ln by!es/sec!or)
/*
*
*
*

Calculate Lhe nunber of blocks nlssing fron Èrack 0 (those that would
be chere if the diskette I'ere uniformly fornatted).
The noúna1 tr:ack
size equals the nuinber of secÈors per track on the rest of the disk
(obtaíned fron the drlver-specific
unit infornation
table).
: nornaf -track-size

track-0-blocks-nlssing
/*
*

lf the loglcal block nunber of this
requesc, calculate the address.

IF block-nuber
DO
/*

< treck-0-blocks

Set the cylinder

- track-0-blocks

request lndlcates

a track

THEN

and head nmber

to 0 because this

track

cylinder-nun - 0
head-n(rll = 0
equation because dtskette

start

seclor-nun (block-number x device - granular i ty )
(128 bytes/sector)

+ 1

c-2

Add I to th{s
1, noc0

sectors

/*
*

see if

the request goes beyond track

(byÈes- reque s !ed)

(track-0-blocks

btock-number)

THEN

DeviceDdverc Uset'sGuide

SUPPORTINGTHE STANDARDDISKETÎE TORMAT

DO
/*
*
*
*

If th" tequest goèe beyond trsck O, thcn calculare rhe núbèr
of bytes !o read o! lrrite that are pasC Crack 0.
Save the
nunber until track 0 operations aÌ:e conplece.
Then use the
number to complete rhe tead or wríte operatfon.

renainder - bytes-requested
x device - granularity

- (ttack-0-blocks

- btock-number)

END

*
*

Calculation of physical
access track 0.

address is conplete

for

requests thar

RE?URN
END
ELSE
DO

*
*
*
*

If che request is pasÈ Èrack 0, adjust the block nurnber for rhls
request by addint the n({ùber of logical blocks nissing from Èrack
0 and calculacing the cyllnder, head, and sector as if rhÍs !,,/ere
a uniformly - fornatted flexible
disk.

adlusc-bÌock-nl-1ln - block-nunber + ÈÍack,0,blocks,nisslng

Firs!

cafculate rhe cyLinder nunber of rhis requesl

cylinder-nun adjust -b1ock-nun
( !olal-num-of-heads x track sizc)
*

Next caÌculate

the head number

IF total-nurì-of-heads
DO
*

= 1 îHEN

This is a one-slded flexible

diskette

head-nm - 0
END

DeviceDriversUser'scuid€

c-l

SfIPPORTINC THE STANDARD DISKEÎfE

FORMAT

DO
*

This is a double sídèd flèxiblé

terop = adjus!-block-nìrn
tenp
head-nun track-size

diskètte

MOD (track-size

x 2)

END
,.
*

FinaIIy, calculate sector nurber for thts request,
because flexible
diskette sectors star! at 1,

sector-nurn - temp MODtrack-sizè

adding 1

+ 1

AND

c-1

DeviceDriversUsefsGuide

Hard disk drivesobtainedfrom Intel (either separatelyor as part ofcompleresysrems)
haverecordedin speciallocationsinformationaboutwhich tr;cks or whiih sectorsofthe
disk are unreliableand shouldnot be used. When thesehard disksare usedwith sralntel
iSBC 214,iSBC 215c, and iSBC 220controllers,Intel-supplieddevicedriverscan read
this bad track informationand map ou! the unreliableareaswhen formatringthe disk.
With the iSBC 214,iSBC 215G,and iSBC 220conrrollerssupporredby rhe I/O Sysrem,
the information on lhe disk must refer to entire tracksthat are unrelable. The iSBC 214,
iSBC 215G,and iSBC 220 controlle.sformat disksa track at a time, and thereforcare
capablcof mappingout only entire tracks.
To assistin addingthis capabiìiryro rhe driversyou write, this appendixdescribesrhe
format Intel useswhen writing the bad track information. Any hard disk driversyou write
shouldbe ableto obtainthis bad track informationand map out the bad trackswnenever
theyformat rhe disks.
The bad track intbrmationis recordedon the highest-numbered
cylinder- I (the highestnumberedcylinderis reservedfor diagnostictracks).
The last four tracksof that cylindercontainthe bad track information. Each track
containsthe sameinformationbut is formattedwith a different sectorsizer

Track
lnst cylinder- 1, l,ast su.face

128b,'tes/secto.

I-astcylinder- 1,hst surface- 1

256bytes/secror

Lastcylinde.- 1,Inst surface- 2

512bytes/sector

Lastcylinder- 1,Inst surface- 3

1024bytes/sector

If a diskhaslessthanfour recordingsurfaces
(andthereforelessthanfow trackspcr
cylinder),thetrackson thenextcylinder(lastcylinder- 2) areusedfor theremainingbad
lrackinformation.

Devic€DdversUser,sGuide

D.l

f NTERPRNTING BAII TRACK INÍ'ORMATION

Recording the inlormation in four different sector sizesallows the driver to accessthe
informationduring {ormat time, regardlessof the sectorsizechosenby the user. For
example,if the userdecidesto format the disk with a volumegranularity(sectorsize)of
512b)'tes,the driver setsup the controllerfor 512-bytesectorsand accesses
the bad Íack
informationfrom the location(last rylinder - l,last surface.2). Likewise,when
formattingin 1024-bytesectors,the driver obtainsthe bad track infolmation from the
location(last cflinder - 1,last surface- 3).
On eachofthose tracks,1024bytesofbad track informationis recordedfoù times,
gap betweeneachrecording. The multiple
startingat sector0, with a 1024-byte
occurrencesare insuranceagainstbad spotsin this areaof the disk. If an eÍor occurs
r'r'henthe driver attempts to accessthe first occurrenceof the bad track information, rr
tries againwith the secondoccurrence,altd so forth.
The lormat of the bad track information is as follows:
WORD
WORD

Must containthe value0ABCDH
Number ofbad tracksin this tist (maxilnumof255)

Then, for eachbad track,the followinginformationappearsl
WORD
BYTE
BYTE

Cylindernumberofbad track
Surfacenumberofbad track
Scl this field to zero

Figùre D-1 illustratesthe positionof this bad track informationon the disk.

D-2

DeviceDÌiversUserrsGulde

INTERTRtrTING
BADTRACKINFORMATION

sqr.c.F1(r5ÈbnKbrr %
sqrr.ù2(5,!!yù-dód)%
surrc. n.3oo24bf.r.cro.)
sudHn..(at.

rr.trb)

Fisure D-1. lbrmat ofBad Track Infomation

DeviceDrlversUser'sGuide

D-3

82530lerminaldriver 3-14
8274terminaldriver 3-13

A
APC sequences
2-13
attachdevicesystemcalls 8-1
auto-ansìwer
modem2-44
axessequence
andorientation2-21
axessequence
control 6-13

B
badtrackinformationD-l
badtrack/sectorinformation4-16
badtrack andsectors8-11
baudrate
input 2-21,6-13
output2-21,6-14
procedure5-28
BEGIN$LONG$TERM$OP
procedu.e4-21
BIOS$GET$ADDRESS
boardlD 5-13
buffer
.aw inpùt 2.6
TerminalSupportCode 2-7
type-ahead
2-7
buffereddevices6-20
buffers
numberof 4-6
B)'teBucketdriver 3-14

c
cancelI/O procedur€7-1,4
cancelrequests8-2
CANCEL$IO 5-2
CANCELJIO procedure4-5
interrupt-drivendevicesA-42
message-passing
devicesB-7

DeviceDriveB ljsér's cuide

Index-l

INDEX

character
length 6-28
characteristics
of diskettes4-3
closesystemcalls 8-2
closingliles E-5
commondrivers 1-4,2-1,3-2,
5-1,
communication
levels1'1
configuring
devicedrivers9-1
connection
flags 6 t
connection
modes2-16
conÍrolc-harac-ter
redefinition2-43
controlcharacters2-24
output2-17
controlstrings2-12
CONTROL-Ocharacter2-12
CONTROL-Pcharacter
2-10
CONIROL-Qcharacter2-12
CONTROL-Rcharacter2-10
CONTROL-Scharacter2-12
CONTROL-Tcharactcr
2-12
CONTROLUcharacter2-10
CONTROLW character2-12
CONTROL-Xcharacter2-10
CONTROI--Zcharacter2-10
cursoraddressing
offset 2-22
cursorpositioning
2-41
customdrivers 1-4,2-1,3-14,7-l
cylindersize 5-15

D
deletecharacter2-10
deletinglines 2-10
detachdevicesystemcalls 8-1
devicedatastoragearea 5-15
devicedriverconfiguration9-l
devicedriverinterfaces4-1
devicedrivertypes 1-4
devicedrivers
Intel-supplied
3-1
devicedrivers 1-1
devicelìnishprocedure5-11,1-6,9
devicegranularity4-4
deviceinformationscreensg-9
deviceinformationtable 4-5,5-8,6-4,18
device initialiation procedure 5-11, 16, 17

Index-2

DeviceDrivers Usefs Guide

INDEX

deviceinterfaces4-21
deviceinterruptproceútte 5-12,16,21
devicenumbcr l-3
devicestartprocedure5-12,16,L9
devicestopprocedure5-12,16,21
device-unitinformationblock
creating4-8
device-unit
informationblock(DUIB) 4-1,6-3
device-unit
informationscreens9-16
device-unit
number 1-3
discarding
mode 2-11
discarding
output 2-12
diskettecharacteristics4-3
diskettefomat, standardC-l
drivecharacteristics
4-14
drivecharacteristics
E-7
driverinterfaces4-1
drivers
Intel-supplied
3-l
DUIB
creating4-8
DUIB 4-1,6-3
duplex2-20,6-11

E
echocontrol ó-10
*hong 2-17
einptyingt)pe-ahead
buffer 2-10
endof file character2-10
END$LONG$TERM$OP
procedure5-29
escape
sequence2-24,2'1,33
examples
simulation 2-32
translatioo2-29
explicitseeks5-15

F
F$ATTACH requests 8-4
F$CLOSErequests8-5
F$DETACII requ€sts8-4
F$OPEN requests8-4
F$READ requests8-3
F$SEEK requests8-4

DeviceDrivers Ilsey's Guid€

Index-3

INDEX

F$SPECIALrequests8-5
F$WRITE requests8-3
file drivers l-1, 4-2
file marks E-10
finishI/O procedure4-5,7-1,2
FINTSH$IO5-1
FIMSH$IOprocedure4-5
interrupt.driven
devicesA-39
message.passing
devicesB-4
fixedupdate4.6
nowc!ÍEol 2-22,6-26
flùshmode 2-8,17
formattingfracks4-13,8-5
FS$FORMAT$TRACKrequests8-5
FS$GET$BAD$INFO
requests8-11
FS$GET$DRIVE$DATA
requests8-7
FS$GET$TERMINAf$ATTzuBUTES
requests6-E
FS$NOTIFYreqùests8-6
FS$QUERYrequcsts8-6
FS$READ$FILE$MARK
requests8-10
FS$RESET
reqùests8-9
FS$RETENSION$TAPE
.equests8-10
FS$SATISFY
requests8-6
FS$SET$BAD$INFO
requests8-I 1
FS$SET$SIGNAI
requests8-9
FS$SET$TERMINAL$ATTzuBUTES
requests8-8
FS$WRITE$FILE$MARK
requests8-l0

G
GET$IORSprocedure5-29
granularity -4

H
highwatermark 2-23,6-27
high water mark,special 2-24

I
I/O request/rcsultsegment(IORS) 4-9
I/O requests l-6,2-4, 8-l
ICU Merge (ICUMRG) utrlity 9-2, 9-4, 22

ICUMRGutitty 9-2,4,22
impliedseeks5-15

Irdex.4

DeviceDriversUseCsGuide

INDEX

INIT$rO 4-4,5-1
INIT$IO procedure
interrupt-drivcn
devicesA-35
message-passing
devicesB-I
initializeI/O procedure4-4,7-1
inputbaudrate 2-21,6-13
inputparity 2-17,20,6-10,1,1,28
insertingdatainto theinputstream2-50
instance5-13
Intel-supplieddevicedrivers 3-1
interfaces
device4-21
interfaces,
driver 4-1
inte.rupt 5-l
interrupthandler2-3
interrùptlev€l 5-10,6-7
interruptlines 6-7
interrupttask 2'3,5 2,A 45
rnte..uptq/pe ó-17
INTERRUPT$TASK5-2,A-45
interrupt-driven
devices5-1,6-1
introduction1-1
invokingtheUDS urility 9-18
IORS 4-9
iSBC186/224Amulti-peripheral
driver 3-6
iSBC186/410terminaldriver 3-9
iSBC208diskdriver 3-2
iSBC214diskandtapecootroller3-5
iSBC215c diskcontroller3-3
iSBC217Ctapecontroller3-3
iSBC220SMD diskdriver 3-6
iSBC2ó4bubblememorydriver 3-8
iSBC286/10(A)lineprinterdriver 3-8
iSBC534terminaldriver 3-11
iSBC544Aterminaldriver 3-12
iSBX218,4'
diskettecontroller3-4
iSBX218,4diskettedriver 3-5
iSBX251bubblememorydriver 3-7
iSBX350lineprinterdriver 3-8
iSBX351terminaldriver 3-12

L
levelsof communication 1-1
line editingcontrol 6-10

DeviceDrivers Use s Gùide

Iídex.s

INDEX

line protocol 2-20
lhe plotocolindicator6-11
lhe terminator2-10
line terminator,special2-10
line-editbuffer 2-7
line-editingfunctions 2-9
line-editing
mode 2-17
link parameters6-29
lockingthe terminat 2-49
logicaladdresses4-21
long-termoperatioN 2-4,5.28
low water rnark 2-23,6-n

M
MassStorageController(MSC)driver 3-2
message
5-1,5.23,6-42
message
task 5-3,B-8
MESSAGE$TASK
B-8
message-passing
devices5-1,6-l
mode
flush 217
line-editing2.17
specialcharacter 6-25,30
terminal4-15
transparent2-E,17
modem2-44,22
modemindicator2-20
modes
connection2'16
terminal2-18
MSCd.iver 3-2
MULTIBUSI interruptless
drivers6-1
MULTIBUS U drivers ó-1

N
normalmode 2-11
notificationof drivedooropen 4-14
NOTIFY procedure 5-26
notiryrequests8-6
NUM$BUFFERS2.2,4-6

Irdex-6

DeviceDriversUset'sGuide

INDEX

o
op€lÌ systemcalls 8-2
openingfiles 84
optimizingsccks2-5
OSCcontrol 2-17
OSCsequences
2-12,26,27,6-10
outputbaudúte 2-21,6-14
outpùtcontrolcharacters2-77,6-10,23
outputmedium2-20,6-11
outputmode 2-11
outputPariry2-17,20,6-10,12,28
overflowoffset 2-22
overlappingseeks2-5

P
parity
'r,put2-17,20,6-10,28
o[lpnt 2-17.2Ct,
6-10,28
physicaladdresses
4-21
physicallink 2-23
physicallink parameters6-27
port ó-1
positioning
thecùrsor2-41
priority 5-11

o
queryreqùests8-ó
queueI/O procedure4-5,?-1,3
queuesize 5-13
QUEUE$IO 5-2
QUEUE$lOprocedure
interrupt-driven
devicesA-40
message-passing
devicesB-5
procedure
4-5
QUEUE$IO
quotingcharacter2-10

R
RAM driver 3-15
random accessdrivers l-4, 2-1,3-2, 5-l

DeviceDrivers UseÉsGuide

Index-7

INDEX

randomaccess
supportroutines
interrupt-drivendevicesA-34
message-passing
devicesB-1
rawinputbuffer 2-ó,ó-19
readrequests8-3
rcadsystcmcalls 8-2
redefiningcontrolcharacteÉ2-43
redisplayinglines
2-10
requestqueue2-3,7-5
retries2-5
retryingI/O requests5-14

s
satisÙrequests8-ó
screenheight 2-21
scrccnwidth 2-21
scrollingcount 6-20
scrollingmode 2-11,12
scrollingnumber2-21,6-14
SCSIdriver 3'9
seekoptimization2-5
seekoverlap2-5
seeksystemcalls 8-2
SEEK$COMPLETE
procedure5"15,27
seeking8-4
seeks
explicit5-15
implìed5-15
signalcharacters4-15,8-9
s'mùlal10n
l-2), J I
softwarecontrolstrings2-12
specralarray 2-25
specialcha.actermode 6-25,26,30
specialcharacters2-22
specialhighwatermark 2-24,6-29
specialline terminator2-10
specialsystemcalls 8-2
stacksize 5-11,6-6
standarddìsketteformat C-1
startingoutput 2-12
stopbits 2-24,6-28
stoppingoutput 2-12
stuffingdatainto the inpùtstream2-50

Inder-8

DeviceDriversUser'sGuide

INDEX

T
tape drive.s4.14
tape file marks 4-15
tape requests8-10

task
interfupt 5-2
message5-3
terminalanswerprocedure6-7,31,36
terminal attributes8
terminalcharacter
sequences
2-26,40
terminalcheckprocedure6-8,32,37
TerminalCommunications
Controllerdriver 3-10
terminal drivers 7-4,2-1,3-9
terminaldriversó-1
terminalfinishproccdureó-ó,31,34
te.minalflags 6-11
terminalhangupprocedve 6-7,32,3'7
terminalI/O 2-6
terminalinitialization
procedureó-6,31,32
terminalmodeinformation4-15
terminalmodes2-18
terminalmutualexclusion
procedure6-30
terminaloutput 2-11
terminaloutputprocedttre6-7,32,44
terminalsetoutputbuffersizeprocedìire6-30,31
terminalsetupprocedure6-6,31,34
TerminalSupportCode 6-1,6-14
TerminalSupportCodeinpurbuffer 2-7
t€minal utilityprocedvre6-7,32,15
t.ackformatting4,13,8-5
tracksize 5-14
translation2-21,25,29,6-13
t.ansparent
mode 2-8,17
q?e of terminalinte..upt 6-17
type-aheadbuffer 2-7
typesof devicedrivers l-4

DevlceDrivers UserJsGulde

Irdex-g

INDEX

U
UDS errormessages
9-19
UDS utility 9.2,4
unit informatiolscreens9-14
unit informationtable 4-5,5-13,6-9,lE
unit number l-3
unlockingthe terminal 2-49
updatetimeout 4-5
User DeviceSupport(UDS) utility 9-2
UserDeviceSupportUtility (UDS) 9-4

v
volumechaogenotfication 2-3

w
write requests 8-3
write systemcalls 8-2

Index-10

DeviceDrivers Useis Guide

INTERNATIONAL
SALES
OFFICES
INTEL
CORPORATION
3065BowertAvenue
SantaClara,California
95051
BELGIUM
IntelCorporatron
SA
RuedesCottages
65
8 - 1 1 8B
0russels
DENMARK
Inte{DenrÍdrkAJ5
Glentevej6l-3rd
Floor
dk-2400
Copenhagen
E N GL A ND

(tJ.K.)LfD.
IntelCorporation

I n t e l J a p aK
n.K.
Flower-HillShin-machi
1-23-9,5hinrna(hi
15
Seîagaya-ku,-fokyo
NETHERLANDS
IntelSemi(ondudor(NetherlandB V.)
AlexanderpoonSuilding
Marten Meesweg93
3068 Rotterdam

PO.8ox92
Hvanìveien
4
N,2013,Skjetten

Wiltshire5N31RJ
Swindon,
FINLAND
IntelFinlandOY
R!o5ilante
2
00390Hesinki
FR,ANCE
lntelParis
1 RueEdison'8P
303
78054St.-Quentin"en-Yveline!
Cedex
ISRAEL
IntelSemr(onducîorr
LTD.
AtrdrmlndustrialPark
NeveSharet
P.O.Box43202
Tel"Aviv
61430
IIALY
IntelCorporation
5.P.A.
E/4
Milandfiori,Palazzo
(Milano)
Assago
20090

SPAIN
lntel lberia
CalleZurbaran28-IZQDA
28010Madrid
SWEDEN
ÌnìelSwedenA.B.
Dalvée9en24
S - 1 7 13 6 S o l n a
5WITZERLAND
lntel semi(onductorA.G_
lalaakerrtrósse
17
4125Glattbrugg
CH-8065zurich
WESTGERMANY
Intel5emicondu(torG N.8.H27
Seidlestrasse
D-8000Munchen

intel'
REQUEST
FORREADER'5
COMMENTS

i R M X lor . 3
Volume2
user'sGuide5
461845-001

lntel5 fechnicalPublications
Deparrmentj
attemptto providepublications
thèt meetîhe needsof all
your (ommeots
lnlel productusers.Thi5form letsyoupartìcipate
process.
directlyin the publication
wr I helpuscorreatandimproveour publi
Source Exif Data:
File Type : PDF
File Type Extension : pdf
MIME Type : application/pdf
PDF Version : 1.4
Linearized : No
XMP Toolkit : Adobe XMP Core 4.2.1-c041 52.342996, 2008/05/07-21:37:19
Create Date : 2008:05:16 11:02:15-01:00
Modify Date : 2016:12:22 07:41:33-08:00
Metadata Date : 2016:12:22 07:41:33-08:00
Producer : itext-paulo (lowagie.com)[JDK1.1] - build 132
Format : application/pdf
Document ID : uuid:f8bc1628-1b6b-a24b-9eda-15ceeacfeb7d
Instance ID : uuid:09bff26d-a76b-154d-bc5e-cdde438a793c
Page Layout : SinglePage
Page Count : 832

EXIF Metadata provided by EXIF.tools

461845 001_Extended_i RMX_II.3_Volume_2_Users_Guides_1988 001 Extended I RMX II.3 Volume 2 Users Guides 1988

461845-001_Extended_iRMX_II.3_Volume_2_Users_Guides_1988 461845-001_Extended_iRMX_II.3_Volume_2_Users_Guides_1988

Navigation menu

Versions of this User Manual:

Views

Navigation