MOCA DeveloperGuide

REDPRAIRIE CORPORATION

MOCA 2009.1

Developer  Guide

MOCA - VERSION 2009.1

Developer Guide Information in this document is subject to change without notice. Companies, names, and data used in eamp!es herein are "ctitious un!ess otherwise noted. #o part of this document ma$ be reproduced or transmitted in an$ form or b$ an$ means, e!ectronic or mechanica!, for an$ purpose, without epress written permission of %ed&rairie Corporation.  2002'2009

%ed&rairie Corporation. A!! rights r eser(ed.

Microsoft, M), and *isua! +asic are registered trademars, and -indows and -indows # are trademars of Microsoft Corporation. Orac!e is a registered trademar and Orac!e Ca!! Interface and &/)/ are trademars of Orac!e Corporation, %edwood )hores, Ca!ifornia. #I3 is a registered trademar of he Open 4roup.

%ed&rairie Corporation 20500 )wenson 6ri(e -auesha, -isconsin 781: &hone 2:2.815.2000 ;
Table of Con Content tents s

INTRODUCTION....................................1

Managed and #imple Managed Met(ods.............. .3'

MOCA Mission Statement..........................................1 Statement..........................................1

COM Met(ods........................ Met(ods..................................... ................................ ................... .3)

Client Application Applications........ s................... ..................................... ..........................1 1

Java Met(ods....................... Met(ods..................................... ........................... .................... ....... .3)

 Available Services.................... .............. ............1 ............1

XML Element es!riptions....................... es!riptions..................................... .............. .4*

The RedPrairie “Thin Client Architecture...................! Architecture...................!

Tri--er De(inition iles..............................................,! ,!

The Client.......... Client..................... ..................... ..................................... ...........................!

Trigger +mplementation e,inition.......................... e,inition.......................... .42

The Server.........................................................!

Trigger isable e,inition......................... e,inition....................................... .............. .43

Thin Client "mplementation.........................................# "mplementation.........................................#

Trigger Enable e,inition........................ e,inition...................................... .................. .43

 A Sample Application................ .............. .............. ......# ......#

XML Element es!riptions....................... es!riptions..................................... .............. .44

Client Application...............................................#

Documentin- Commands and Tri--ers...................., Tri--ers....................,

 Available Services.................... .............. ............# ............#

XML Element es!riptions....................... es!riptions..................................... .............. .4%

Services and $ibraries provided b% MOCA.................& MOCA................. &

"nitiali6in- Component $ibraries...............................,' $ibraries...............................,'

INSIDE  MOCA..................................... MOCA.....................................

C Component Libraries......................... Libraries.......................................... ................. .4)

Modules...................................................................... '

Managed Component Libraries........................... Libraries.............................. ... .4)

MOCA Component "nter(ace......................................' "nter(ace......................................'

COM Component Libraries........................ Libraries.................................... ............ .4)

Command )*ecution................................................1+ )*ecution................................................1+

$icensin- Component $ibraries................................2+ $ibraries................................2+

Command Pipes.......................................................1, Pipes.......................................................1,

C Component Libraries......................... Libraries.......................................... ................. ."*

Command Tri--ers...................................................1 Tri--ers...................................................1

Managed Component Libraries........................... Libraries.............................. ... ."*

Command Separators..............................................1 Separators..............................................1

COM Component Libraries........................ Libraries.................................... ............ ."*

Command Groupin-.................................................1& Groupin-.................................................1&

7ersionin- Component $ibraries..............................21 $ibraries..............................21

Command Concatenation.........................................1& Concatenation.........................................1&

C Component Libraries......................... Libraries.......................................... ................. ."-

Conditional Command )*ecution.............................1/ )*ecution.............................1/

Managed Component Libraries........................... Libraries.............................. ... ."-

)*pressions0 unctions and $iterals.........................1' $iterals.........................1'

COM Component Libraries........................ Libraries.................................... ............ ."-

)*ceptions................................................................ !,

"nitiali6in-0 $icensin- and 7ersionin- 8ava Component

Remote Command )*ecution...................................!2 )*ecution...................................!2

$ibraries.................................................................... 2!

Parallel Command )*ecution...................................!& )*ecution...................................!&

MOCA !ROCESSES............................ $#

3ritin- scripted commands 4in Groov%5....................!& Groov%5....................!&

MOCA Connection Mana-er.....................................2# Mana-er.....................................2#

MOCA COMMAND RE!OSITOR"...........#1 ...........#1

MOCA Server Process Module.................................22 Module.................................22

Component $evel De(inition iles.............................#! iles.............................#!

Con(i-urin- MOCA...................................................22 22

C Component Libraries......................... Libraries.......................................... ................. .32

The 3indo9s MOCA Re-istr%..................................2 Re-istr%..................................2

Managed Component Libraries............................ Libraries................................ .33

Conne!tion Manager Con,iguration....................... ."

COM Component Libraries.................................... Libraries.................................... .33

#erver /ro!ess Con,iguration................................ Con,iguration................................ .")

Java Component Libraries.......................... Libraries..................................... ........... .33

atabase Con,iguration......................... Con,iguration......................................... ................ .-

Using Multiple Component Types.......................... Types.......................... .34

Environment Con,iguration.................................... Con,iguration.................................... .4

XML Element es!riptions........................ es!riptions..................................... ............. .3"

#ervi!e Con,iguration.......................... Con,iguration....................................... ................... ...... .

Command De(inition iles........................................# iles........................................#

Tas0 Tas0 Con,iguration......................... Con,iguration................................................. ........................ .'

Lo!al #ynta$ Commands.......................... Commands....................................... ............. .3%

Job Con,iguration.......................... Con,iguration....................................... ......................... ............ .%*

C and #imple C &un!tions..................................... &un!tions..................................... .3'

EM# Con,iguration....................... Con,iguration..................................... .......................... ............ .%2

#e!urity Con,iguration......................... Con,iguration...................................... ................... ...... .%4

srv
Li!ense Con,iguration........................... Con,iguration............................................ ................. .%

srv
O1ner Con,iguration........................... Con,iguration.............................................. ................... .%%

srv
The :;"< MOCA Re-istr%........................................&/ Re-istr%........................................&/

srv+nitiateCommand....................... srv+nitiateCommand.......... .......................... ....................... .......... -*

MOC egistry &ile #e!tions and ame56alue /airs

srv+nitiateCommand&ormat...................... srv+nitiateCommand&ormat......... ......................... ............ .-*

.......................... ....................................... .......................... .......................... ........................... .............. .%)

srv+nitiate+nline....................... srv+nitiate+nline.................................... ............................... .................. -*%

E$ample MOC egistry &ile................................ &ile................................ .'2

srv+nitiate+nline&ormat....................... srv+nitiate+nline&ormat......... ........................... ................... ...... .-*'

Startin- the Connection Mana-er............................./, Mana-er............................./,

srvMain......................... srvMain....................................... ........................... .......................... ............. .-*'

MOCA Console........................................................./2 /2

srvMo!a=CloseConne!tion...................................-*) srvMo!a=CloseConne!tion................................... -*)

Reloadin- Server Memor%......................................../ Memor%......................................../

srvMo!a=E$e!ute................................................. -*)

Shuttin- Do9n the Connection Mana-er................../& Mana-er.................. /&

srvMo!a=+nitConne!tion........................ srvMo!a=+nitConne!tion.......... ............................. ............... .--*

Tracin- the Server Process....................................../& Process....................................../&

srvegisterata: srvUnregisterata.................... .--*

%UI&DING A COM!ONENT....................' ....................'

srvelease>eepalive........................... srvelease>eepalive.............. .......................... .................. ..... ---

The basic C component............................................/' component............................................/'

srve?uest>eepalive......................... srve?uest>eepalive............ ........................... .................... ...... ---

CUSTOMI(ING

SER*ER......# ......#

srvesults...................... srvesults................................... .......................... .......................... ............. .--2

&I%RARIES............................. .............................$ $

srvesultsdd........................ srvesultsdd..................................... .............................. ................. .--3

MOCA $ibrar% Dependencies...................................' Dependencies...................................'

srvesults+nit..................... srvesults+nit.................................. .......................... ...................... ......... .--3

 AP" unctions................. .............. .............. ....... ..... ..' '

srvollba!0........................ srvollba!0..................................... .......................... ...................... ......... .--4

#erver Library 7srvLib8.......................... 7srvLib8........................................... ................. .)

srv#etCommand#o!0et....................................... .--4

srvdd#9Lesults........................ srvdd#9Lesults........... .......................... ......................... ............ .)

srv#eteturn#tatus...................... srv#eteturn#tatus.................................... ........................ .......... .--"

srvCombineMo!aataes......................................)% srvCombineMo!aataes..................................... .)%

srv#et#erver/ort......................... srv#et#erver/ort...................................... ......................... ............ .--"

srvCombineesults..................... srvCombineesults.................................. ........................... .............. .)%

m!!isableutoCommit...................... m!!isableutoCommit........ ............................... ................. .--

srvCommit.................... srvCommit.................................. ........................... ............................ ............... .)'

m!!EnableutoCommit......................... m!!EnableutoCommit............ ............................ ............... .--

srvEnumeratergList............................................. .)'

m!!E$e!#tr...................... m!!E$e!#tr................................... .................................... ....................... .--

srvErroresults...................... srvErroresults................................... ............................... .................. -**

m!!Close....................... m!!Close.................................... .......................... .......................... ............. .--%

srvErroresultsdd....................... srvErroresultsdd.................................... ....................... .......... .-**

m!!+nit...................... m!!+nit................................... ........................... ............................... ................. .--%

MOCA

T)E MOCA

srvE$e!ute,terCommit: srvE$e!ute,terollba!0

Miscellaneous $ibrar% 4mislib5........................11& 4mislib5........................11&

.......................... ....................................... .......................... .......................... ......................... ............ .-*-

miss!iiTo
srv&reergList....................... srv&reergList.................................... .......................... .................. ..... .-*2

mis@aseConv......................... mis@aseConv...................................... .............................. ................. .--'

srv&reeMemory....................... srv&reeMemory.................................... ............................. ................ .-*2

misynC(ar!at....................... misynC(ar!at..................................... .............................. ................ .--)

srv;etCommand#o!0et...................... srv;etCommand#o!0et........ ............................... ................. .-*2

misCi#tr!mp....................... misCi#tr!mp..................................... .................................. .................... .--)

srv;eteededElement........................ srv;eteededElement........... .......................... ................. .... .-*3

misCi#tr!mp: misCi#trn!mp................................ .--)

srv;et#erver/ort.................................................. -*4

misCi#trepla!e................................................... -2*

srv
misCi#trepla!ell............................................... -2*

srv
misCi#trstr...................... misCi#trstr.................................... ........................... ........................ ........... .-2-

srv
misyn#print,....................... misyn#print,..................................... ........................... .................. ..... .-2-

srv
misyn#tr!at...................... misyn#tr!at................................... ........................... ..................... ....... .-2-

srv
misyn#tr!py....................... misyn#tr!py.................................... .......................... ................... ...... .-2-

misyn#trn!at..................... misyn#trn!at.................................. .......................... .................... ....... .-22

dbollba!0......................... dbollba!0...................................... ................................... ...................... -3)

misyn#trn!py..................... misyn#trn!py................................... ................................ .................. .-23

db#et#avepoint........................... db#et#avepoint........................................ ......................... ............ .-3)

misEnd&ind&ile........................ misEnd&ind&ile...................................... ............................. ............... -23

dbollba!0To#avepoint........................................-3) dbollba!0To#avepoint........................................ -3)

misE$pand6ars................. misE$pand6ars.............................. .................................... ....................... -24

db;ete$t6al.................. db;ete$t6al............................... .......................... ........................ ........... .-4*

mis&ind&ile........................ mis&ind&ile..................................... .......................... ...................... ......... .-2"

dbConne!t.......................... dbConne!t........................................ ........................... .................... ....... .-4*

mis&ormatate..................................................... -2"

dbClose.......................... dbClose........................................ ........................... ........................ ........... .-4*

mis&ormatTime................... mis&ormatTime................................ .................................. ..................... -2

S>$ $ibrar% 4s?l$ib5.......................................1,1 4s?l$ib5.......................................1,1

mis
s?l&reeesults....................... s?l&reeesults.................................... ............................... .................. -4-

mis
s?l;et@inaryata.......................... s?l;et@inaryata....................................... ....................... .......... .-4-

mis
s?l;et@inaryataLen............................ s?l;et@inaryataLen.............. ............................. ............... .-42

mis
s?l;etataType.................. s?l;etataType................................ .................................. .................... -42

mis
s?l;et&loat......................... s?l;et&loat....................................... ........................... .................... ....... .-42

mis
s?l;etLong............................ s?l;etLong......................................... .......................... .................. ..... .-43

mis
s?l;ete$to1...................... s?l;ete$to1................................... ............................... .................. -43

mis
s?l;et/revo1........................ s?l;et/revo1...................................... ............................. ............... -44

mis
s?l;eto1......................... s?l;eto1...................................... .......................... ...................... ......... .-44

mis
s?l;et#tring........................... s?l;et#tring........................................ ............................... .................. -44

mis
s?l;et6alue..................... s?l;et6alue.................................. .......................... ........................ ........... .-4"

misLogebug.......................... misLogebug....................................... ............................. ................ .-2)

s?l+sull........................ s?l+sull...................................... ........................... .......................... ............. .-4"

misLog+n,o....................... misLog+n,o.................................... .......................... ........................ ........... .-2)

s?lemoveo1........................ s?lemoveo1..................................... ............................ ............... .-4

misLogAarning...................... misLogAarning................................... ............................... .................. -2)

s?l#etate......................... s?l#etate...................................... .......................... ...................... ......... .-4

misLogError.......................................................... -2)

s?l#et&loat......................... s?l#et&loat...................................... .................................. ..................... .-4

misM"ata...................... misM"ata................................... ................................... ...................... -3*

s?l#etLong........................... s?l#etLong........................................ ................................ ................... .-4%

mis#trepla!e....................... mis#trepla!e.................................... .......................... .................. ..... .-3-

s?l#et#tring........................... s?l#et#tring........................................ .......................... .................. ..... .-4%

mis#trepla!ell....................... mis#trepla!ell.................................... ........................... .............. .-3-

OS )ncapsulation $ibrar% 4oslib5...................1,& 4oslib5...................1,&

misToLo1er: misToLo1er: misToUpper............. misToUpper.......................... ......................... ............ -3-

OS $ibrar% Mailbo* unctions........................1,/ unctions........................1,/

misTr!................. misTr!.............................. .......................... ..................................... ........................ -32

osM@XCreate.......................... osM@XCreate....................................... .......................... ................ ... .-4'

misTrim: misTrim.................... misTrim................................. ............................ ............... -32

osM@Xe!v......................... osM@Xe!v...................................... ................................. .................... -4'

misTrimLen................... misTrimLen................................ ........................................ ........................... -32

osM@Xe!vTimeout............................................. -4)

misTrimL.................. misTrimL............................... .......................... ............................. ................ .-33

osM@X#end........................... osM@X#end......................................... ............................... ................. -"*

misTrim#trn!mp.................. misTrim#trn!mp............................... ................................. .................... .-33

osM@XClose.......................... osM@XClose....................................... ............................... .................. -"*

misTrim!py: misTrimn!py: misTrimL!py............. -33

osM@X>ill.......................... osM@X>ill....................................... .......................... ...................... ......... .-"-

mis6alidateatetime&ormat.............. mis6alidateatetime&ormat. .......................... .................... ....... -34

OS $ibrar% Memor%@mapped iles unctions.121 unctions .121

D= $ibrar% 4db$ib5..........................................1#, 4db$ib5..........................................1#,

osCreateMap&ile......................... osCreateMap&ile...................................... ......................... ............ .-"-

dbCommit...................... dbCommit................................... .......................... .......................... ............. .-34

osMap&ile.......................... osMap&ile....................................... .......................... ...................... ......... .-"-

dbE$e!@ind......................... dbE$e!@ind...................................... .......................... .................... ....... .-34

osUnmap&ile......................... osUnmap&ile...................................... ............................... .................. .-"2

dbE$e!#tr........................ dbE$e!#tr..................................... .......................... ........................ ........... .-3

osLo!0Mem........................ osLo!0Mem...................................... ........................... .................... ....... .-"2

dbE$e!#tr&ormat....................... dbE$e!#tr&ormat..................................... ........................... ............. -3%

osUnlo!0Mem........................ osUnlo!0Mem..................................... ............................... .................. -"3

OS $ibrar% TCP"P and SocBet unctions......12# unctions..... .12#

m$mlpply#tyles(eet&rom&ile 5

osTC/Listen...................... osTC/Listen................................... ................................... ...................... -"3

m$mlpply#tyles(eet&rom#tring..........................- m$mlpply#tyles(eet&rom#tring.......................... -

osTC/Conne!t...................... osTC/Conne!t................................... .......................... .................. ..... .-"3

m$mlCloneode................................................... -%

os#o!0!!ept...................... os#o!0!!ept................................... ................................. .................... -"4

m$mlCreatettribute............................................. -%

os#o!0#end........................ os#o!0#end..................................... .......................... .................... ....... .-"4

m$mlCreateCT#e!tion........ m$mlCreateCT#e!tion...................... ........................... ............. -'

os#o!0e!v..................... os#o!0e!v.................................. ..................................... ........................ -"4

m$mlCreateComment...........................................-' m$mlCreateComment........................................... -'

os#o!0#(utdo1n.................................................. -""

m$mlCreateo!ument.......................................... -)

os#o!0Close...................... os#o!0Close.................................... ................................... ..................... -"

m$mlCreateo!ument&ragment...........................-) m$mlCreateo!ument&ragment........................... -)

os#o!0ddress....................... os#o!0ddress.................................... .............................. ................. -"

m$mlCreateElement............................................. -)

os#o!0Errno......................................................... -"

m$mlCreate/+........................ m$mlCreate/+..................................... ............................... .................. -%*

os#o!0Error......................... os#o!0Error...................................... ................................. .................... -"

m$mlCreateTe$tode...........................................-%* m$mlCreateTe$tode........................................... -%*

os#o!0Aait................... os#o!0Aait................................ .......................... ........................... .............. -"%

m$mlErrorumber........................... m$mlErrorumber............. ........................... ..................... ........ .-%-

os#o!0AaitTimeout............... os#o!0AaitTimeout............................ ............................... .................. -"%

m$mlErrorTe$t............. m$mlErrorTe$t.......................... ........................... ............................ .............. .-%-

OS $ibrar% iles%stem unctions...................12& unctions...................12&

m$ml;etttribute.................................................. -%-

osC(dir........................ osC(dir..................................... .......................... ............................ ............... .-"%

m$ml;etttributeode........................ m$ml;etttributeode.......... ........................... ................. .... .-%2

osCreateir....................... osCreateir.................................... .......................... ...................... ......... .-"'

m$ml;etttributes................................................ -%2

osemoveir....................... osemoveir.................................... ................................. .................... -"'

m$ml;etttrame................................................ -%3

os;etCurrentir........................ os;etCurrentir..................................... ........................... .............. .-"'

m$ml;etttr#pe!i,ied........................................... -%3

OS $ibrar% Miscellaneous unctions.............12/ unctions............ .12/

m$ml;etttr6alue.................. m$ml;etttr6alue............................... ............................... .................. -%4

os#leep......................... os#leep...................................... .......................... .......................... ............. .-"'

m$ml;etC(ara!terata........................................ -%4

osError......................... osError....................................... ......................................... ........................... -"'

m$ml;etC(ara!terataLengt(............................. -%4

os;et6ar................. os;et6ar.............................. .......................... ................................. .................... -")

m$ml;etC(ildodes.............................................-%" m$ml;etC(ildodes............................................. -%"

os;eteg........................ os;eteg..................................... .......................... ........................ ........... .-")

m$ml;eto!ument............................................... -%"

os/rint&ile........................ os/rint&ile...................................... .................................... ...................... .-")

m$ml;eto!umentElement..................................-% m$ml;eto!umentElement.................................. -%

os#nprint,........................ os#nprint,..................................... .......................... ........................ ........... .-")

m$ml;etElements@yTagame.............................-% m$ml;etElements@yTagame............................. -%

)vent $ibrar% 4evtlib5......................................1+ 4evtlib5......................................1+

m$ml;et&irstC(ild 5 m$ml;etLastC(ild................ -%%

Event Library &un!tions........................ &un!tions........................................ ................ -*

m$ml;et+tem...................... m$ml;et+tem................................... ........................... ..................... ....... .-%%

evte?uest...................... evte?uest................................... .......................... ........................ ........... .--

m$ml;etamed+tem...................... m$ml;etamed+tem......... .......................... ....................... .......... -%'

evtealiBe...................... evtealiBe.................................... ....................................... ......................... -2

m$ml;ete$t#ibling 5 m$ml;et/revious#ibling...-%' m$ml;et/revious#ibling... -%'

evt&reeEvents...................... evt&reeEvents.................................... ................................ .................. .-3

m$ml;etodeListLengt(...................................... -%'

MOCA
m$ml;etodeame............................................. -%)

m$mlddttribute...................... m$mlddttribute................................... ........................... .............. .-3

m$ml;etode6alue................... m$ml;etode6alue................................ ........................... .............. -%)

m$mlddComment............................................... -3

m$ml;etodeType................... m$ml;etodeType................................ ............................ ............... -'*

m$mlddElement........................ m$mlddElement..................................... ......................... ............ .-4

m$ml;et/arentode............................................ -'*

m$mldd/+........................ m$mldd/+..................................... .......................... ...................... ......... .-"

m$ml;et/+ata....................... m$ml;et/+ata.................................... .......................... ................ ... .-'-

m$mlddTe$tode............. m$mlddTe$tode.......................... .......................... ..................... ........ .-"

m$ml;et/+Target.............. m$ml;et/+Target........................... .................................... ....................... -'-

m$mlppendC(ild......................... m$mlppendC(ild...................................... ....................... .......... .-

m$ml;etTagame............ m$ml;etTagame......................... .................................... ....................... -'m$ml
m$ml+nsert@e,ore...................... m$ml+nsert@e,ore................................... ........................... .............. .-'2


m$ml/arse&ile 5 m$ml/arse#tring........................ m$ml/arse#tring........................ -'3

/ortumber /roperty 7MM8........................ 7MM8............................. ..... .2*"

m$mlemovettribute..................... m$mlemovettribute........ .......................... ..................... ........ .-'3

Environment /roperty 7MM8............................. 7MM8............................. 2*

m$mlemovettributeode..................................-'4 m$mlemovettributeode.................................. -'4

 utoCommit /roperty 7MM8............................. 7MM8............................. 2*

m$mlemoveC(ild...................... m$mlemoveC(ild................................... ......................... ............ .-'4

Methods......................................................... !+

m$mlemoveamed+tem..................................... -'"

+nitialiBe Met(od 7MM8...................... 7MM8................................... ................. .2*

m$mlepla!eC(ild....................... m$mlepla!eC(ild..................................... ......................... ........... -'"

E$e!ute Met(od 7MM8...................... 7MM8................................... ................. .2*%

m$ml#etttribute..................... m$ml#etttribute.................................. .......................... ................ ... .-'

Close Met(od 7MM8........................ 7MM8......................................... ................. 2*'

m$ml#etttributeode..........................................-' m$ml#etttributeode.......................................... -'

Data T%pe Conversion............................................!+/ Conversion............................................!+/

m$ml#etttr6alue................ m$ml#etttr6alue............................. .......................... .................... ....... .-'%

DE*E&O!ING MOCA

m$ml#etC(ara!terata..................... m$ml#etC(ara!terata........ .......................... ................... ...... .-'%

A!!&ICATIONS IN -A*A.....................+1+ .....................+1+

m$ml#etamed+tem............................................. -''

3ritin- a Component..............................................!1! .!1!

m$ml#etode6alue.............................................. -''

MocaResults........................................................... !1,

m$ml#et/+ata.................... m$ml#et/+ata.................................. ................................. ................... -')

MocaConte*t.......................................................... !1

m$ml#tart/arser...................... m$ml#tart/arser.................................... ............................. ............... -')

)*ception andlin-................................................!1& .!1&

m$ml#top/arser................................................... -')

Runtime vs. ChecBed )*ceptions..................!1' )*ceptions..................!1'

m$ml#tring 5 m$mla1#tring........................ m$mla1#tring................................ ........ -)*

8D=C Connections.................................................!!+ .!!+

m$mlArite&ile 5 m$mla1Arite&ile...................... -)*

8ava Client Access via MocaConnection................!!+ MocaConnection................!!+

MOCA COM ACCESS.......................1+ .......................1+

 Advanced Topics............... Topics............... .............. ......... ..... ..... ....!!+ .!!+

The MOCA Server Obects $ibrar%.........................1'! $ibrar%.........................1'!

MOCA E% SER*ICES.....................++1 .....................++1

The MOCADataT%pes )numeration.......................1', )numeration.......................1',

De(inin- 3eb Services...................................!!1 Services...................................!!1

7alues............................................................ 1',

Service Con(i-uration iles............................!!! iles............................!!!

The MOCA)rrors )numeration..............................1', )numeration..............................1',

=uildin- the 3eb Service Application.............!!2 Application............ .!!2

7alues............................................................ 1',

Callin- 3eb Services.....................................!!2 Services.....................................!!2

The MOCAResults Obect......................................1'2 Obect......................................1'2

Calling our Aeb #ervi!e ,rom 6isual C............... 22'

Properties.. Properties............ ..................... ..................... ............................... .....................1'2 1'2

 Authentication................ ............... ......... ..... ...!!/ .!!/

Methods......................................................... 1'

 Appendi* E MOCA 3eb Service Con(i-uration Con(i-uration

The MOCAServerAccess Obect............................1'& Obect............................1'& Properties.. Properties............ ..................... ..................... ............................... .....................1'& 1'& Methods......................................................... 1'& =uildin- a COM@based MOCA component.............1'' component.............1''

..............+,# C &IENT   ACCESS *IA &IENT  A CCESS *IA MMDA..............+,#  ADO Recordset Overvie9................. ....... ..... ..... ....!+# ....!+# Disconnected Recordsets..............................!+# Recordsets..............................!+# Recordset Persistence...................................!+, Persistence...................................!+, MOCA Data Access Component............................!+, Component............................!+, DataAccess Obect........................................!+, Obect........................................!+, Properties.. Properties............ ..................... ..................... ............................... .....................!+2 !+2

COM!ONENTS AND

DTD............. DTD....................... .................... ..................... .............................. ...................!!' !!'

I N T R O D U C T I O N

C/apter 

1

1

/at are t/e Ob2e0tiv es of MOCA3

Introdu0tion  An intro introduc ductio tion n to to MOCA MOCA his section is intended to pro(ide the reader with a basic, high' !e(e! understanding of MOCA. )peci"ca!!$ we wi!! discuss= 

he objecti(es of MOCA 



he topograph$ of %ed&rairie>s ?hin C!ient@ architecture



)er(ices and !ibraries pro(ided b$ MOCA 

MOCA Mission Stateent he mission of MOCA is to pro(ide our de(e!opment sta with a techn echnic ica! a! infr infras astr truc uctu ture re that hat per permit mits and and pro promot motes the the interoperabi!it$ of components in a simp!e, eecti(e, and non' imp!ementation speci"c manner. %ed&rairie product de(e!opment strateg$ promotes the creation of ?hin@ c!ients. hat is, the de(e!opment of c!ient app!ications that hat are are not, ot, them themse se!( !(es es,, respon sponsi sib! b!e e for for ?sig ?signi ni" "cant cant@ @ trans transact action iona! a! or computat computation iona! a! acti(it acti(it$ $. Instea Instead, d, the c!ient c!ient app!ication is responsib!e for the presentation reBuirements, not hea($ processing. In this t$pe architecture, it is critica! to ha(e proper de!egation of responsibi!ities. -e ha(e coined the term ?C!ient)er(ices@ to depict our approach to this. In this scheme, we ha(e a high'!e(e! app!ication topograph$ that !oos !ie this=

Client MOCA

Available Servi0es

I N T R O D U C T I O N

Ipleentation /at is a 4T/in5 Servi0e6 Copon Client3 as a ent3 Non6 Goal of MOCA

Our de"nition of a component is an iso!atab!e and indi(idua!!$ dep!o$ dep!o$ab!e ab!e imp!em imp!ement entati ation on of functi functiona ona!it !it$ $ that that has a nown nown interface. It>s as simp!e as that. -e, as users of the ser(ices, are not eposed to the imp!ementation detai!s of the components. -e  just  just now now what what functi functiona ona!! prob!e prob!em m it so!(es so!(es and and under understa stand nd how how to acti(ate it. In terms of MOCA, a!! ser(ice components are nown b$ a name. he name is de"ned b$ a (erbnoun c!ause combination. )ome eam eamp! p!es es of thes these e inc! inc!ud ude e  Move  Move Invento Inventory ry,, Alloca Allocate te Shipme Shipment nt  Locati  Location, on, and  and Rat  Rate e Ship Shipmen mentt. It is important to stress that the objecti(e of MOCA is to pro(ide the the fram framew ewor or  enab enab!i !ing ng thin thin c!ie c!ient nts s to acti acti(a (ate te ?)er ?)er(i (ice ce Comp omponen onents ts@. @. MOCA MOCA doe does not not spec pecif$ if$ imp imp!eme !ement ntat atio ion. n. herefore, as !ong as ser(ices can u!timate!$ communicate with MOCA MOCA,, the the imp! imp!em emen enta tati tion on and and spec speci" i"c c imp! imp!em emen enta tati tion on techno!og$ is !eft to the component de(e!opers.

T/e Red!rairie 4T/in Client5 Ar0/ite0ture  As state stated d abo(e, abo(e, %ed&ra %ed&rairi irie>s e>s approa approach ch to app!ica app!icatio tion n de(e!opment re(o!(es around the idea of ?thin@ c!ients. )imp!$ put, put, ?hi ?hin n C!ie C!ient nts@ s@ are are app! app!ic icat atio ions ns whos whose e resp respon onsi sibi bi!it !it$ $ is !imite !imited d to user user inter interact action ion,, i.e. i.e. disp!a disp!a$in $ing g infor informat mation ion on the screen and getting input from the user. he u!timate eamp!es of  thin thin c!ie c!ient nts s are are inte intern rnet eti int ntra rane nett app! app!ic icat atio ions ns.. App! App!ic icat atio ions ns running in the contet of a browser ha(e (irtua!!$ no abi!it$ to stor store e data data,, and and a (er$ (er$ !imit !imited ed abi! abi!it it$ $ to e(en e(en stor store e cont conte ett information, within the app!ication. he$ must therefore re!$ on a ser(er to perform the bu! of the processing reBuired b$ the app! app!ic icat atio ion. n. he he simp simp!e !est st diag diagra ram m of thin thin c!ie c!ient nt topo topogr grap aph$ h$ wou!d !oo !ie this=

T/e Client %esponsib!e for disp!a$ing data and 3

I N T R O D U C T I O N

Network Communication

T/e Server  %esponsib!e for most of the rea!

4

I N T R O D U C T I O N

T/in Client Ipleenta Ipleentation tion %eca!!ing the (iew of MOCA as an infrastructure from abo(e, !et>s !oo at a bit more detai!. p!oding each of the three boes from the origina! diagram= C!ient app!ications pro(ide mechanisms for disp!a$ing data and interacting with the user u ser.. C!ients interact with the ser(er (ia standard )/ or Component ?Commands@. he ser(er responds with a comp!etion status and data.  he c!ient is responsib!e r esponsib!e for taing appropriate action.

MOCA recei(es a ?command@ of some ind. It is interpretedD a decision is made regarding whether to eecute )/ or a component command. If the command is )/, it is eecuted, if it is a component, it is initiated.  After the component comp!etes, the comp!etion status and an$ data returned b$ the component is sent bac to the reBuesting c!ient.

5

I N T R O D U C T I O N

Client MOCA

Available Servi0es

Components must be capab!e of being acti(ated b$ MOCA. Components must be capab!e of returning a response ?pacage@ to MOCA . Imp!ementation is not a MOCA concern.

A Saple Appli0ation o better i!!ustrate the bene"ts of MOCA, !et>s run through a samp samp!e !e app!ic app!icat atio ion. n. /et> /et>s s use use the the eam eamp! p!e e of an emp! emp!o$ o$ee ee database. t start that connection, connection, the app!ication wou!dn>t be ab!e to come up. In *isua! +asic, this can can be done in the ?form !oad@ e(ent, or something simi!ar. simi!ar. /et>s run through the t$pic $pica! a! data'dri(en (en app!ica ication.  App!ic  App!icati ations ons of this this t$pe t$pe gener genera!!$ a!!$ ha(e ha(e an initia initia!! ?!oou ?!ooup@ p@ scre screen en or form. he user is presented with se(era! "e!ds to "!! in, which a!!ow the user to perform a !ooup on one or more of those "e!ds.

6

I N T R O D U C T I O N

hen hen,, afte afterr the the !oo !ooup up,, the the user user is pres presen ente ted d with with a !ist !ist of  matching entries.
he component that wou!d do the !ooup wou!d imp!ement the ?!ist ?!ist emp!o$e emp!o$ees@ es@ comman command. d. It wou!d wou!d tae as argument arguments s the "e!ds from the employees database employees database entit$ corresponding to the emp!o$ emp!o$ee ee I6, I6, "rst "rst name, and !ast !ast name name F!et>s F!et>s sa$ employee_id, employee_id,  frst_  frst_nam name e, and last_nameG. last_nameG. After After the user "!!s in the the !astHname !astHname "e!d in the !ooup form F!et>s sa$ the user enters ?smith@G and presses the ?!ooup@ button, the c!ient maes a ca!! to the MOCA  ser(er, sending it the command= list employees where last_name = ‘smith’

 he ser(er turns that command into a ca!! to the appropriate component. he component responds responds with the reBuested !istings FMOCA components a!wa$s return data to the ca!!er in tabu!ar formG, the ser(er sends the resu!ts bac to the c!ient, and the c!ient disp!a$s them in a !ist.

7

I N T R O D U C T I O N

hen the user se!ects one from the !ist F!et>s sa$ the second one=
8

I N T R O D U C T I O N

6epending on the imp!ementation, the c!ient ma$ choose to get more detai!ed information than the ?!ist emp!o$ees@ component pro(ided. &erhaps &erhaps there>s a ?!ist emp!o$ee emp!o$ee detai!s@ component, which taes on!$ an emp!o$eeHid "e!d, and it pro(ides a!! the infor informati mation on the c!ient c!ient needs needs to procee proceed d F!ist F!ist emp!o$ emp!o$ee ee detai!s detai!s where where emp!o$ee emp!o$eeHid Hid  J891'2 J891'29'8 9'892 928>G 8>G.. ither ither wa$, wa$, the c!ient c!ient app!ication is now disp!a$ing the main data entr$ form.

9

I N T R O D U C T I O N

 After  After the user has modi" modi"ed ed the emp!o$ emp!o$ee> ee>s s recor record, d, some some action action must be taen to signa! to the c!ient app!ication that it>s time to submit the changes.

he c!ient app!ication ca!!s bac to the ser(er, submitting the command ?change emp!o$ee where emp!o$eeHid J891'29'8928> and "rstHname> "rstHname> and !astHname>)mith> !astHname>)mith> and etc.@. If the user chose to de!ete that emp!o$ee, the c!ient wou!d ha(e had to send a ?remo(e ?remo(e emp!o$ee emp!o$ee where where emp!o$eeHi emp!o$eeHid>89 d>891'29 1'29'8928 '8928>@ >@ comman command. d. If the user user had chosen chosen to create create a new emp!o$ee emp!o$ee record, the$ wou!d>(e started on the main data entr$ form and the the c!ie c!ient nt wou!d wou!d>(e >(e subm submit itte ted d the the comm command and ?add ?add emp! emp!o$ o$ee ee where emp!o$eeHid >E> and etc.@. )imp!e maintenance programs such as the one i!!ustrated here are the bread bread and butter butter of MOCA'base MOCA'based d app!ication app!ications. s. MOCA  pro(id pro(ides es some some suppor supportt for *isua! *isua! )tudio )tudio and other other -indo -indows ws de(e!opment too!s (ia the MM6A COM object Fsee chapter 10G. he eamp!e shown here wou!d probab!$ be bui!t with *isua! +asic or CK and the MM6A too!.

10

I N T R O D U C T I O N

/at is provided provided 8it/ MOCA

Servi0es and &ibraries provided b7 MOCA MOCA consists of three basic pieces= 1. MOCA MOCA pro( pro(id ides es the the fram framew ewor or  for for the the de(e de(e!o !opm pmen entt and and dep!o$ment of )er(ice Components as de"ned abo(e. -hi!e this this is rea! rea!!$ !$ more more of a phi!o phi!oso soph ph$ $ than than spec speci" i"c c soft softwa ware re de!i(erab!e, it is an important part of MOCA. 2. MOCA MOCA pro(id pro(ides es mechani mechanisms sms enab!ing enab!ing de(e!ope de(e!opers rs to creat create e and and dep! dep!o$ o$ MOCA MOCA ser( ser(er ers. s.
11

I N T R O D U C T I O N

12

T ) E

M O C A

E N G I N E

C/apter 

+

13

9un0tions /at is &o0al of t/e S7nta:3 Server 

Inside MOCA This chapter provides a comprehensive comprehensive description o the pieces that comprise the MOCA runtime environment!

Modules -hen -hen refe referr rrin ing g to the the MOCA MOCA ser( ser(er, er, we are are actu actua! a!!$ !$ ta! ta!in ing g abou aboutt a series ries of # or #I3 #I3'bas 'based ed app! app!ic icat atiions. ons. hes hese e app! app!ic icat atio ions ns ha(e ha(e been been crea create ted d usin using g the the C prog progra ramm mmin ing g !anguage. Once the Orac!e or )/ )er(er database engine has been been star starte ted d on the the ser( ser(er er mach machin ine, e, the the MOCA MOCA Conn Connec ecti tion on Manager process FmocaconmgrG is started. his t$pica!!$ occurs during the boot process. On #, it happens when the MOCA  ser( ser(ic ice e star starts ts.. he he MOCA MOCA Conn Connec ectio tion n Mana Manage gerr proc proces ess s is responsib!e for starting ser(er processes as needed to ser(ice an$ incoming c!ient reBuests for the entire ser(er en(ironment.
MOCA Coponent Interfa0e he MOCA Component MOCA  Component In(ocation /anguage F!oca! s$ntaG is not a progra programmi mming ng !angua !anguage, ge, in the t$pica! t$pica! sense sense.. Instea Instead, d, it is intended to be a high !e(e! method of acti(ating components. /oca! s$nta has the fo!!owing characteristics= /oca /oca!! s$nt s$nta a can can be used used to in(o in(oe e an$ an$ A#)I A#)I )/ )/ statement. )tandard )/ s$nta, L)/CL for eamp!e, ma$ sti!! be used, if the statement is enc!osed in de!imiting characters FsBuare bracets= ? N@G. he main focus of !oca! s$nta commands is to pro(ide a simp!e and consistent interface to ser(er'side components. 

/oca! s$nta can a!so be used to in(oe an$ seBuence of  script script statements. statements. Much !ie )/ stateme statements, nts, the script script must must be enc! enc!os osed ed in doub doub!e !e'b 'bra rac cet ets. s. F F script NNG NNG he 

14

T ) E

M O C A

E N G I N E

S7nta: of Copon ent Re;uest s

scripting !anguage we use is one that a!!ows access to a(a objects and c!asses, and a!! (ariab!es on the MOCA stac  are a(ai!ab!e a(ai!ab!e to the scripting scripting engine. engine. -e use the 4roo($ 4roo($ scri script ptin ing g !ang !angua uage ge to pro( pro(id ide e scri script ptin ing g capa capabi bi!it !it$ $ in MOCA. he MOCA parser eamines incoming commands in an eort to determine how to best ser(e them. It compares the command to components de"ned within the ser(er. ser(er. 

 A!! !oca! !oca! s$nta s$nta comman commands ds are de"ned de"ned within within a repositor$ on the ser(er and !oaded into memor$ at startup time for optimum performance. 

Coand E:e0ution In order to assure Peibi!it$, actions associated with a!! MOCA  compo componen nents ts are de"ned de"ned within within the reposi reposito tor$ r$ on the ser(er ser(er.. Qowe( Qowe(er er,, it is (er$ (er$ impor importan tantt to unders understan tand d the under! under!$in $ing g concepts with regard to command determination and eecution. his his sect sectio ion n out! out!in ines es the the meth method ods s b$ whic which h comm comman ands ds are are interpreted and eecuted. s it>s assumed to to be a component component reBuest reBuest.. he pre'pro pre'processin cessing g that goes on on with )/ statements comes in the fo!!owing forms= 

Rvaria#le %ep!aced b$ the (a!ue of varia#le. varia#le. he (a!u (a!ue e wi!! wi!! be in sing! ing!e e Buot Buotes es if the  (ariab  (ariab!e !e is a string. string. If the (ariab!e (ariab!e was set in the where'c!ause with an operator other than ?@, the the (a!ue wi!! wi!! be #//. #//. If used with the ?onstac@ directi(e as in ?Rvaria#le ?Rvaria#leK Konstack @, @, the (a!ue wi!! be 1 if  the (ariab!e is on the stac and 0 otherwise.

15

T ) E

M O C A

E N G I N E



R'varia#le R'varia#le %ep!aced b$ the (a!ue of varia#le. varia#le. he (a!u (a!ue e wi!! wi!! be in sing! ing!e e Buot Buotes es if the  (ariab  (ariab!e !e is a string string.. his his is identi identica! ca! to the $varia#le  $varia#le  s$nta abo(e, ecept the (a!ue of  the (ariab!e is used regard!ess of the operator used in the where'c!ause.



RRvaria#le% RRvaria#le %ep!aced b$ the (a!ue of the en(ironmen en(ironmentt (ariab!e (ariab!e varia#le. varia#le. he (a!ue wi!! be in sing!e Buotes.



RSvaria#le RSvaria#le %ep!aced b$ ?varia#le ?varia#le@ @ and the  (a!ue  (a!ue of of the (ariab! (ariab!e. e. If the the (ariab! (ariab!e e is not not set, set, rep!aced rep!aced b$ the the string string ?11@. ?11@. If the (ariab!e (ariab!e was set in the where'c!ause with an operator other than ?@, that operator is used Fe.g. !ist parts where where unitHcost unitHcost T 700G. his s$nta can a!so a!so be etend etended ed to inc!ud inc!ude e the tab!e name and a dot Fi.e. $%ta#lename!varia#le $%ta#lename!varia#leGG, in orde orderr to a(oi a(oid d ambig ambigui uit$ t$ in mu!t mu!tip ip!e !e't 'tab ab!e !e  joins  joins.. here here is a!so a!so the the capab capabi!i i!it$ t$ to Ucas UcastU tU the the datat atat$p $pe e of a parti articu cu!a !arr (ari (ariab ab!e !e,, in two two spec specia ia!! circ circum umst stan ance ces= s= varia#le= varia#le=date  date  turns into into toHd toHdat ateF eFvaria#le varia#leGG, whi!e varia#le= varia#le=raw  turns into the (a!ue of varia#le without varia#le without Buotes. he he date date s$nt s$nta a is usef usefu! u! for for te!! te!!in ing g !oca !oca!' !' s$nta where'c! 'c!auses that a particu!ar !ar  (ariab  (ariab!e, !e, if it come comes s in, is a date date (aria (ariab!e b!e.. he s$nta is actua!!$ not needed for Orac!e, but )/ )er(er reBuires it.

16

T ) E

M O C A

E N G I N E

RSne&varia#le'oldvaria#le RSne&varia#le'oldvaria#le %ep!aced b$ ?ne&varia#le ?ne&varia#le@ @ and the (a!ue of  the oldvaria#le. oldvaria#le. A!! other other beha(io beha(iorr associate associated d with the $% s$nta $% s$nta is sti!! honored.





RV %ep!aced b$ a!! the (ariab!es in the wher where' e'c! c!au ause se to the the curr curren entt comp compon onen ent, t, in order der, in the the same same form orm as that hat use used for for ?RSvaria#le ?RSvaria#le@. @. *ariab! ariab!es es that that ha(e ha(e a!re a!read$ ad$ been been refe refere renc nced ed are are not not adde added d un!e un!ess ss the the  (ariab  (ariab!e !e was refer referenc enced ed using using the ?eep@ ?eep@ directi(e as fo!!ows= ?Rvaria#le ?Rvaria#leK Kkeep@. keep@.



R If a sing!e URU appears b$ itse!f Fi.e. spaces spaces immediate immediate!$ !$ fo!!ow fo!!ow itG, itG, then then it is !eft !eft a!o a!one. ne. his his a!!o a!!ows refe referrring ring to Orac!e ac!e database !ins Fe.g. select rom ta#le $ lin(nameG. lin(nameG.


order_header.*, order_detail.* order_header, order_detail order_header.ordnum order_header.ord num = order_detail.ordnum order_detail.o rdnum @+order_header.ordnum @+order_header.o rdnum @*

the joined joined co!umn co!umn ordnum was ordnum was represented once in the join Forder_header!ordnum ) order_detail!ordnumG order_detail!ordnum G and once as a spec pecia! ia! RS (ar (ariab! iab!e e F$%order_header!ordnum $%order_header!ordnumG. G. #O #O == %efe %efere renc nces es to a!! RS (ari (ariab ab!e !es s need need to come come befo before re the the reference to the specia! RV s$nta, because the references are rep!aced in order, and referring to speci"c (ariab!es with RS taes the (ariab!e out of the RV rep!acement !ist. Comp Compon onen entt reBu reBues ests ts Fcom Fcomma mand ndsG sG cons consis istt of two two dist distin inct ct segments= the command name and statement Bua!i"ers. he he comp compon onen entt name name Fcom Fcomma mand nd name nameGG de"n de"nes es an acti action on or dire direct cti( i(e e upon upon whic which h the the ser( ser(er er acts acts.. he he command name is in the form ?(erb noun c!ause@. he  (erb  (erb de"ne de"nes s the the action actionDD the noun noun c!ause c!ause de"nes de"nes a target target of  of  the action and ma$ inc!ude grammatica! s$nta Fan, a, for, the, etc...G. etc...G. A//OCA A//OCA I#*#O% I#*#O%W W, %A %A )QI&M# )QI&M#,, 

17

T ) E

M O C A

E N G I N E

/I) I#*#O%W
1. he "rst, "rst, and perhap perhaps s most common common Bua!i"er Bua!i"er a!!owe a!!owed d in a statement Bua!i"er is one of the form varia#le varia#lee*pression. e*pression. his ind ind of epression epression sets the  (ariab  (ariab!e !e named named varia#le to varia#le to the (a!ue described b$ the gi(en e*pression. e*pression. *ariab!es can be an$ word, cons consis isti ting ng of !ett !etter ers s FA' FA'Ya Ya'X 'XNG NG,, numb number ers s F0' F0'9N 9NG, G, underscores F?H@G and periods periods F?.@G. )ee the note abo(e about reser(ed reser(ed words. words. More More about epression epressions s !ater. !ater. his his is the the wa$ wa$ that that argu argume ment nts s to C func functi tion ons s that that imp!ement MOCA ser(ices get "!!ed in. 2. Anothe Anotherr (a!id epr epres essio sion n is one of the the form form varia#le op e*pression, e*pression, where op  op  is an operator other than ?@, name name!$ !$ FZ, T, Z, Z, T, [, /I\ /I\,, #O /I\G /I\G.. ItLs ItLs important to note that Bua!i"er epressions of this form do not mae an$ named argument data a(ai!ab!e to C func functi tion ons, s, un!e un!ess ss the$ the$ spec speci" i"ca ca!! !!$ $ !oo !oo for for it usin using g sr(numerateArgs/istF G. 8. Anot Anothe herr Bua!i Bua!i"e "err simi simi!a !arr to the ones abo(e abo(e are of the form varia#le I) varia#le I) #ON #ON #//. #//. )tatement )tatement Bua!i" Bua!i"ers ers in this form ha(e the same !imitations as those of t$pe 2.

18

T ) E

M O C A

E N G I N E

]. Another (a!id Bua!i"er is one where the who!e epression is enc!osed in sBuare sBuare bracets. F? N@G Once again, and !ie the !ast two forms, these Bua!i"ers are not used for "!!ing in arguments to C code. 7. he on!$ on!$ other (a!id (a!id Bua!i" Bua!i"ers ers are two two inds of specia! specia!  (ariab  (ariab!e !e refere reference nces. s. One is URSvaria#le URSvaria#leU, U, and and the the other is URVU. hese are (er$ simi! mi!ar to their counterparts in the )/ substitution arena. RSvaria#le RSvaria#le !oos  !oos up varia# varia#le le in the eecution contet Fmore on that !aterG and puts that (ariab!e, a!ong with the the oper operat ator or used used to de"ne de"ne it. RV taes taes the entir entire e where'c!ause for the current command and uses it for the curre urrent nt comm comman and, d, in much uch the same same wa$ as RSvaria#le RSvaria#le.. hes hese e speci specia! a! epr epres essi sion ons, s, and the their ir counterparts in the )/ parsing, are the on!$ wa$ that Bua!i"ers in forms 2'] wi!! be referenced. ach command argument can be speci"ed as reBuired and ha(e an associated e$word with it. his a!!ows for the more more ng! ng!is ish' h'!i !ie e crea creati tion on of comm comman and d s$nt s$nta a..

)tatem )tatement ent Bua!i" Bua!i"ers ers are de"ned de"ned as reBuir reBuired ed for most most of the intrinsic commands $ou wi!! encounter. $pica!!$, on!$ the /I) t$pe commands are unrestricted. his a!!ows for the scanning of  the entire contents of a master tab!e.

19

T ) E

M O C A

E N G I N E

!ipe inforation fro one 0oa nd to anot/er<

Coand !ipes  A feature feature of of MOCA is MOCA  is the abi!it$ to pipe the output of an$ se!ect or command into another command for eecution. he pipe F^G character is used to join commands. his feature has !imited use in a prod produc ucti tion on en(i en(iro ronm nmen ent, t, but but much much more more use use duri during ng de(e!opment and testing. In order to understand pipes, we must get into a discussion of  what we refer to as command streams, pu#lishin+, data streams and conte*t. conte*t. A command stream refers to a stream of  commands, tied together with pipes andor command separators.  "u#lish  "u#lishin+ in+ is the the proc proces ess s of mai maing ng data data a(ai a(ai!ab !ab!e !e to othe otherr comman commands ds downstr downstream eam in the command command stream stream.. )/ se!ect se!ect statements, for eamp!e, pub!ish the data that is the resu!t of the Buer$ Buer$. &ub!ished &ub!ished data from from a command command or )/ statement statement are often referred to as the ?resu!ts@ of the command.  A data stream refers to a!! the data that is ?!i(e@ as a command stre stream am eec eecut utes es.. hat hat is, is, a!! a!! data data pub! pub!is ishe hed d b$ a!! a!! of the the comm comman ands ds proce process ssed ed so far far in the comm comman and d stre stream. am.
 After  After the eecut eecution ion of the "rst "rst comman command, d, the data data stream stream cons consis ists ts of the the resu resu!t !t of the the )/ )/ se!e se!ect ct stat statem emen ent. t. After fter eecution of the second command, the data stream consists of  the resu!t resu!ts s of both the )/ se!ect se!ect statemen statementt and the allocate location command, location command, after the eecution of the !ast command, the data stream consists of the resu!ts of a!! three commands. Conte*t or conte*t level refers to on!$ the data within the data stream that is re!e(ant to the eecution of the net command in the the comm comman and d stre stream am.. In our our eam eamp! p!e, e, sa$ sa$ the the )/ )/ se!e se!ect ct stat statem emen entt retu return rned ed si si lodnums. lodnums.
20

T ) E

M O C A

E N G I N E

the allocate allocate location location comm comman and d on!$ on!$ refe refers rs to the the "rst rst row row retu return rned ed b$ the the se!e se!ect ct comman command. d. he he cont conte ett for for the the "rst "rst in(o in(oca cattion ion of the the move inventory  inventory  comm command and cons consis ists ts of the the resu!ts of the allocate location command location command and the resu!ts of the )/ se!ect statment. statment. he contet at an$ point in time is simp!$ a bacward (iew of a!! the resu!ts of the commands eecuted up to that particu!ar point in time. he contet is important because the contet is where MOCA  !oos for command arguments if the$ are not ep!icit!$ speci"ed. #otice that in the abo(e eamp!e, allocate location is ca!!ed with no stateme statement nt Bua!i"e Bua!i"err, no where'c! where'c!aus ause. e. hat>s hat>s o becaus because e MOCA nows that allocate location  location  ta taes lodnum as an argument. argument. -hen it sees that that the command command has been in(oed in(oed,, it !oos through through the contet for for un"!!ed arguments. )ince lodnum is in the output of the se!ect statement, MOCA "nds it, and "!!s in the argument to the imp!ementation of allocate location. location. he resu!ts of a piped seBuence of commands are the cumu!ati(e resu!ts resu!ts of the indi(idua! indi(idua! eecutions eecutions of the "na! "na! command. command. )o in the eamp!e abo(e, if the move move invent inventor ory  y  comman command d gets gets eecut eecuted ed si times, times, and each each in(oca in(ocatio tion n return returns s one row row, the resu!ts returned from the stream consists of a!! si rows of data returned from a!! of the eecutions of move inventory .  An eamp!e eamp!e of piping piping output output from from one command command to anothe anotherr in a production en(ironment wou!d be as fo!!ows= produce countsheet where arecod = /012 and wr34on = ))  print file where delfl5 = 6 and copies = '


6uring piping, as with triggers and separators, either the entire command stream wors, or it a!! ro!!s bac.

21

T ) E

M O C A

E N G I N E

Tri==er 0oands off of t/e initiatio n of anot/er 0oa nd<

Coand Tri==ers One of the most powerfu! aspects of MOCA is the imp!ementation of command triggers. A command trigger is a ser(er command that triggers o the eecution of another ser(er comman command. d. his featur feature e he!ps he!ps to insure insure that that certai certain n functi functions ons occu occurr beca becaus use e of an acti action on that that occu occurs rs in the the faci faci!i !it$ t$,, not not necessari!$ because an app!ication modu!e was smart enough to eecute a !ist of commands am amp! p!es es of comm comman and d trig trigge gers rs are are the the insta insta!! !!at atio ion n spec speci" i"c c components reBuired to send information to a host computer. $pica!!$, &rite host receipt, receipt , &rite host shipment, shipment, and &rite host adustment transactions eist. In straig aight !ine coding en(iro en(ironme nments nts,, some some recei( recei(ing ing progra program m wou!d wou!d eecut eecute e a &rite host receipt t$pe function after a pa!!et of product was recei(ed. -ith ith MOCA, OCA, the the &rite &rite host host receip receiptt   command is p!aced as a trigg trigger er to the the move inventory   command. An$time in(entor$ is mo(ed, mo(ed, the &rite host receipt command receipt  command is eecuted. #atura!!$, the &rite host receipt transaction receipt  transaction needs to be inte!!igent enough to chec the source area and destination area to insure product is mo(ing from epected receipts into the faci!it$. In order to faci!itate eicient eecution of command triggers, man$ of the stand standar ard d intr intrin insi sic c comm comman ands ds pub! pub!is ish h data data as the the resu resu!t !t of  eec eecut utio ion. n. his his pub! pub!is ishe hed d data data is a(ai a(ai!a !ab! b!e e as inpu inputt for for a comm comman and d being being eec eecut uted ed as a comm comman and d trig trigge gerr. he he move inventory  comm comman and d pub! pub!is ishe hes s both oth the the sour source ce area area and and dest destin inat atio ion n area area of the the mo(e mo(e bein being g perf perfor orme med. d. sin sing g this this method, method, the &rite host receipt simp!$ receipt  simp!$ checs the pub!ished data and eits if no other wor needs to be performed. It shou shou!d !d be note noted d that that comm comman and d trig trigge gers rs do not not aec aectt the the output or resu!ts resu!ts of the command command on which the$ are p!aced. he resu!t su!ts s of a trigg rigger er>s >s eec eecut utio ion n are are disc discar arde ded d afte afterr the the comp!etion of the trigger stream.

22

T ) E

M O C A

E N G I N E

!rodu0e Group Coands To=et/e 0opou nd r  0oa nds<

Coand Separators )ometimes it is desirab!e to create a series of commands that eec eecut ute e indep indepen ende dent nt!$ !$ of one one anot anothe herr, but but must must eith either er a!! eecute successfu!!$ or a!! ro!!bac. his can be accomp!ished b$ using the command separator Fsemico!on''?D@G character. -hen parsing, the ser(er process wi!! search for a command separator. If found, the command stream prior to the separator is eecuted as if it was the on!$ on!$ comma command nd being being eecut eecuted. ed. A!! command command pipes and command triggers are eecuted as norma!. If there are more commands be$ond the separator, the$ are a!so parsed and eecuted. An eamp!e of command separator usage is as fo!!ows= 5enerate counts ; produce countsheet where arecod = /012 and wr34on = ))  print file where delfl5 = y and copies = ' ; produce countsheet where arecod = /;9/ and wr34on =   print file where delfl5 = y and copies = '

%eme %ememb mber er, in the the pre( pre(io ious us eam eamp! p!e, e, as befo before re,, a!! a!! of the the commands, pipes, and triggers must successfu!!$ eecute or a!! of it wi!! be ro!!ed bac.

Coand Groupin= -hat if $ou want se(era! commands to eecute independent!$ of  each other, but the$ need to eecute as the tai! end of a piped stream_ As ma$ or ma$ not be c!ear from the pre(ious pre(ious eamp!e, the command separator a!wa$s groups piped streams together. he herefo efore we nee need a wa$ wa$ to gro group semi semico co!o !on' n'se sep parat arated ed comman commands ds so that the$ the$ can partici participat pate e in a pipe stream stream.. he answ answer er is the the comm comman and d grou groupi ping ng brac brace ets ts Fbra Fbrace ces, s, cur! cur!$ $ bracets, ?`? and and ?@G. An$thing inside of braces gets grouped together as one !ogica! command, so it can be put direct!$ into a command stream. he he eamp eamp!e !e from from abo( abo(e e can can be modi modi"e "ed d to i!!u i!!ust stra rate te how how commands can be grouped=

23

T ) E

M O C A

E N G I N E

Do t/is> t/en do t/is?

5enerate counts  { produce countsheet where arecod = /012 and wr34on = ))  print file where delfl5 = y and copies = '< produce countsheet where arecod = /;9/ and wr34on =   print file where delfl5 = y and copies = ' }

he resu!ts of a braceted command seBuence are the resu!ts of  the !ast !ast command command eecut eecuted. ed. -hen -hen a brace braceted ted seBue seBuence nce is p!aced on the tai! end of a pipe stream, the ru!es for accumu!ation of resu!ts from the pipe stream a!so tae eect. he contet from piped commands within the bracets, howe(er, does does not carr$ carr$ o(er o(er outside outside of the bracets bracets.. here herefor fore e the command stream oo stream oo-#a -#ar-# r-#a. a. might  might ha(e a dierent resu!t than /oo-#ar0-#a.. /oo-#ar0-#a.. %eme %ememb mber er, in the the pre( pre(io ious us eam eamp! p!e, e, as befo before re,, a!! a!! of the the commands, pipes, and triggers must successfu!!$ eecute or a!! of it wi!! be ro!!ed bac.

Coand Con0atenation Comman Command d conca concaten tenati ation, on, simi!a simi!arr in man$ man$ wa$s wa$s to comman command d sepa separratio ation, n, a!!o a!!ows ws mu!t mu!tip ip!e !e in(o in(oca cati tion ons s of a comm comman and d to contr contribu ibute te to the same resu! resu!tt set. his is most most usefu! usefu! when combi combined ned with command command groupin grouping. g. his his is better better i!!ustra i!!ustrated ted with an eamp!e= -e wou!d want a )!otting c!ient to eecute a command !ie list location flters. flters. In a combine combined d 6M p!usCA/M p!usCA/M insta!!ation insta!!ation,, the command cou!d be mapped to= remote @@dmplus_host> list location filters ? remote @@calm_host> list location filters

he resu!t sets of both wi!! be combined, seam!ess!$, seam!ess!$, to the c!ient. +e awar aware, e, howe howe(e (err, that that the the resu resu!t !t sets sets of both both part parts s of a concat ncate enate nated d com command mand must must ha(e ha(e ide identic ntica! a! name ames and and datat$pes, or the beha(ior of the resu!ting command stream wi!! be unde"ned.

24

T ) E

M O C A

E N G I N E

Onl7 e:e0ute a 0oa nd if?

Conditional Coand E:e0utio E:e0ution n It is a!so a!so poss possib ib!e !e to perf perfor orm m comm comman ands ds and and trig trigge gers rs in a conditiona! mode. his is t$pica!!$ usefu! in a situation when the resu!ts of a gi(en command on!$ shou!d be modi"ed for a certain segment of the acti(it$ performed. he s$nta of a conditiona! command is= conditionale*pression!! command F command F or "command if  if conditionale*pression se1uence# se1uence#G e$se command For "commandse1uence commandse1uence# #GN  A cond conditi itiona ona!! comma command nd can can opti optiona ona!!$ !!$ be be fo!! fo!!owe owed d up b$ and and e!se e!se b!oc, which, in turn, can contain another conditiona! command. remote@remotesys> do some commandA else do some other commandA

Much Much !ie !ie conc concat aten enat ated ed comm comman ands ds,, di dieren erentt bran branch ches es of  conditiona! eecution must pub!ish a consistent resu!t set, so that, if ca!!ed as the tai! end of a pipe, the resu!ts wi!! be joined together correct!$.  A condit condition iona! a! epre epressi ssion on is a speci specia! a! epres epressio sion n that that is e(a!ua e(a!uated ted in a boo!ean boo!ean contet. An epression can be a simp!e comparison between two (a!ues FZ,Z, T,T, , [, /I\, #O /I\G, a sing!e (a!ue epressions Fto chec for eistence of a (ariab!e, for inst instan ance ceG, G, a F[G F[G fo!!o fo!!owe wed d b$ a sing sing!e !e (a!u (a!ue e Fto Fto chec chec  for for non' non' eis eiste tenc nce e of a (ari (ariab ab!e !eG, G, or a set set of cond condit itio iona na!! epr epres essi sion ons s Foptiona!!$ in parenthesesG, separated b$ the words and or and or or . A  more comp!ete de"nition of epressions wi!! wi! ! fo!!ow. fo!!ow. Consider the mo(ement of in(entor$ into an area that no !onger reBuires the tracing of indi(idua! case identi"ers Fin(sub.ph$Pg and in(sub.idmPg mPgG. nderstanding that hat move inventory  pub!ishes the destination area of the mo(e, the fo!!owing trigger cou!d be p!aced on the command= if @dstare = B7CD/!7B> [update invsuE set phyfl5 = F1F, idmfl5 = F1F

25

T ) E

M O C A

E N G I N E

E:pressions and &iterals

 where suEnum in select invsuE.suEnum from invsuE, invlod where invlod.stoloc = @dstloc and invlod.lodnum = invsuE.lodnum and invsuE.phyfl5 = F6F or invsuE.idmfl5 = F6F>>]

Man$ Man$ time times, s, it is nece necess ssar ar$ $ to perf perfor orm m a more more comp comp!ic !icat ated ed  (ersio  (ersion n of the abo(e abo(e eamp! eamp!e. e. Qow cou!d cou!d the same same tas tas be accomp!ished if we a!so had to account for the possibi!it$ that a!! of the in(entor$ being mo(ed into the 3AM&/ area ma$ not ha(e been traced at the case !e(e! to start with. he conditiona! shown abo(e wi!! fai! if it cannot update something from UWU to U#U. %e(iew the fo!!owing (ariation= [select count*> cnt from invsuE, invlod where invlod.stoloc = @dstloc and invlod.lodnum = invsuE.lodnum and invsuE.phyfl5 =F6F or invsuE.idmfl5 = F6F>]  if @cnt G % and @dstare = B7CD/!7B>> [update invsuE set phyfl5 = F1F, idmfl5 = F1F where suEnum in select invsuE.suEnum from invsuE, invlod where invlod.stoloc = @dstloc and invlod.lodnum = invsuE.lodnum and invsuE.phyfl5 = F6F or invsuE.idmfl5 = F6F>>]

#ow the trigger wi!! on!$ tr$ to perform the update when we ha(e something to update.

E:pressions> 9un0tions and &iterals his his brings brings up the concep conceptt of an e*pression. e*pression. An epression epression is something that can reso!(e to a (a!ue of some sort. pressions can be used in conditiona! statements, statement Bua!i"ers, and remote eecution eecution statements. he "rst, and most common common ind of epression is a literal. literal. /itera!s can can come in man$ shapes= 1. A string string consta constant nt enc!osed enc!osed in sing!e Buotes Buotes or doub!e doub!e Buotes Buotes is a stri string ng !ite !itera ra!. !. am amp! p!e= e= "foo", two Buo Buote "foo", 'bar' 'bar' . If two mars Fwhiche(er ind ind is enc!osing ing the stringG are encountered within the string !itera!, the$ are rep!aced with a

26

T ) E

M O C A

E N G I N E

sing!e Buote mar. A sing!e'Buoted string can tae a doub!e' Buote without without doub!ing it, and (ice'(ersa. amp!e= 'Mike''s Inventory' , "ynvalue'!'" , "ynvalue""y""" . 2. A nume numeri ric c const onstan antt with ith or with withou outt a sign, ign, and with ith or witho without ut a deci decima ma!! poin pointt and and frac fracti tion ona! a! part part,, is a nume numeri ric c !itera!. amp!e= '200, 8.1]179 8. A (ari (ariab ab!e !e refer referen ence ce of the the form form== R varname  varname  is a (ariab!e reference !itera!. !itera!. he (ariab!e referred referred to wi!! be rep!aced at eec eecut utio ion n time time with the (a!u (a!ue e of varname  varname  pu!!ed from the contet. amp!e= R!odnum ]. An en(ironm en(ironment ent (ariab! (ariab!e e referen reference ce of the form= RRvarname RRvarname is an en(ironment en(ironment reference reference !itera!. !itera!. he (ariab!e (ariab!e referred referred to wi!! be rep!aced at eecution time with the (a!ue of varname pu!! pu!!ed ed from from the the !ist !ist of pro process cess en(i en(iro ronm nmen entt (ari (ariab ab!e !es. s. amp!e= RRempnum 7. he wo word 23LL  23LL is a !itera! with no (a!ue. :. A string of charact characters ers enc!osed enc!osed in sBuare sBuare bracet bracets s FUU, UNUG UNUG is a string string !iter !itera!. a!. amp!e= amp!e= barN. barN. -arning. arning. his is rea!!$ rea!!$ just just an etension of the wa$ )/ Bueries are parsed, and the stri string ng enc! enc!os osed ed withi within n the the brac brace ets ts must must ha(e ha(e matc matchi hing ng Buotes, Buotes, much !ie )/ statem statements ents must. must.
S Fp!usG.
27

T ) E

M O C A

E N G I N E

9un0tions

@ship_date + ( 

H* ( days after the shipment date *H

' Fminu minusG sG..
H* /rocessin5 time *H H* Jalf a day Eefore *H



V, ,  Fmu! Fmu!ti tip! p!$ $, di(i di(ide de,, modu modu!u !usG sG.. he he resu resu!t !t is the the product, di(idend or modu!us of the two operands.



^^ Fdou Fdoub! b!e'p e'pip ipe' e''c 'con onca cate tena nati tion onG. G. he he resu resu!t !t is a stri string ng created b$ joining two strings together.



, T, Z, T, Z /I\, #O /I\, I) #//, I) #O #// F!ogica! operatorsG. he resu!t is a boo!ean (a!ue Ftrue or fa!seG based on the comparison of two other (a!ues.



 A#6,  A#6, O% F+oo!e F+oo!ean an operat operator orsG. sG. he !ogica !ogica!! A#6 or O% of  two +oo!ean epressions. If an epression epression is not +oo!ean, +oo!ean, it wi!! be treated as Uis #//U.



[ Funar$ #OG. he !ogica ica! negation of a boo!ean epression. his operator does not appear between two epressions, but must appear before a sing!e sin g!e epression.

 An$ epr epres essio sion n can be enc! enc!ose osed d in parent parenthes heses es for for c!arit$ c!arit$ and and to o(erride defau!t precedence Fwhich is rough!$ the re(erse order of presentation of the operatorsG. @minutes + K% * @hours + > if L@var or @var G (%> M do somethin5 where fullname = @first_nameF F @last_name>

he !ast !ast t$pe of epress epression ion is a functi function on ca!!. ca!!.
28

T ) E



M O C A

E N G I N E

  co%%andF co%%andF G he function returns the tet of the current!$ eecuting commad.



  s&sdateF s&sdateF G %eturns the current date as a COMW&H6AIM. COMW&H6AIM.



G, strin'F G, intF G, (oatF   dateF dateFe*pr G, strin'Fe*pr G, intFe*pr G, (oatFe*pr G aes an$ data t$pe as an incoming parameter and returns a (a!ue of the gi(en t$pe.



G, )pper Fe*pr G   $ower Fe*pr G, %eturns the epression as string, con(erted to !ower case or upper case !etters.



G, rtri%F   tri%F tri%Fe*pr G, rtri%Fe*pr G %eturns the epression as a string with trai!ing whitespace remo(ed.



  d*t&peF d*t&peF G %eturns the database t$pe. t$pe. Current!$, Current!$, (a!id database t$pes are UO%AC/U, UO%AC/U, UM)) UM))/U, /U, and U#O#U. U#O#U. U%%O%U U%%O%U can be returned b$ this function if the database con"guration is in(a!id.



  ne+t,a$F ne+t,a$Fe*pr G %eturns the net (a!ue in the seBuence named b$ e*pr , as a string.



iif F 4oolean  4ooleane*p e*prr, true truee* e*pr5 pr5,, alse alsee* e*pr6 pr677 (a!uates  4oolea  4ooleane ne*pr  *pr , and returns truee*pr  if it e(a!u (a!uat ate es to % %, and and  alse  alsee*p e*pr  r  if it ejjj ejjj(a (a!ua !uate tes s to


  decode8e*pr decode8e*pr,, search, result5, search, result, deault67

29

T ) E

M O C A

E N G I N E

In order to e(a!uate this epression, MOCA compares e*pr  to each search (a!u (a!ue e one b$ one. one. If e*pr   is eBua! to a search, search , MOCA MOCA retu return rns s the the corr corres espo pond ndin ing g result. result. If no matc match h is foun found, d, MOCA MOCA retu return rns s deault, deault, or, if deault is omitted, returns nu!!.. 

$enF $enFe*pr G, G, $en't8e*pr7 $en't8e*pr7 %eturns the !ength in b$tes of a string epression.



8mt, e*pr7   sprintf 8mt, he function function epect epects s  mt   mt  to be a C printf format string. he function app!ies the format epressed b$ mt b$  mt to e*pr .


  d*date8e*pr7 d*date8e*pr7 he function epects e*pr  to   to be either a MOCA date or a string which represents the date as  WWWWMM  WWWWMM66Q 66QQ2] Q2]MI) MI)) ). his his functi function on wi!! wi!! con(er con(ertt this this epression to a string appropriate for the database that is in use. he date wi!! be returned as  WWWWMM  WWWWMM66Q 66QQ2] Q2]MI) MI)) ) for Orac!e Orac!e databa databases ses.. he date date wi!! wi!! be return returned ed as WWW WWWW W'MM'66 'MM'66 QQ QQ2] 2]=MI =MI=) =)) ) for )/ )er(er databases.



  s)*str 8e*pr, 8e*pr, inde*5, len+th67 he function taes the string epression represented b$ e*pr  and and tae taes s a sub' sub'st stri ring ng of it starti starting ng at inde*  inde*  for a !ength of len+th. len+th. inde* in inde* in this case starts with with 1. If len+th is ommitted, end of the input string is assumed.



8search_e*pr, loo(or_e*pr5, startpos67   instr 8search_e*pr, he function searches the string epression represented b$ search_e*pr  for   for the string epressions represented b$ loo(or_e*pr , star starti ting ng at startpos  startpos  withi within n search_e*pr . If  startpos  startpos  is ommit ommitte ted, d, search_e*pr  is searched searched from the beginning of the string.

30

T ) E



M O C A

E N G I N E

n,$ n,$8e*pr, inulle*pr7 If e*pr is dete determ rmin ined ed to be #// #//,, the the epr epres essi sion on repres represent ented ed b$ inulle*pr   is returned, returned, otherwise otherwise e*pr  is returned.



%in %inFe*pr G, G, %a+  %a+ Fe*pr G he functi function on epect epects s a comma' comma'sep separa arated ted !ist !ist of one or more more epr epres essi sion ons s and retu return rns s the the minim minimum umm mai aimum mum  (a!ue.  (a!ue.



  rowco)ntF rowco)ntFresultsetG resultsetG he function epects a resu!t set and returns the number of rows in the gi(en resu!t set.



ser-de/ned )nctions= )nctions= If MOCA does not recogniXe the function that is used in the epres epressio sion, n, it assumes assumes that that it is a userdefned unction. unction. MOCA wi!! eecute the named function in this case as a MOCA MOCA comman command d usin using g the the sr(I sr(Ini niti tiat ateI eIn!i n!ineF neF G A&I. A&I. In order to construct the where'c!ause of this command, the positi positiona ona!! argume arguments nts to the functi function on epres epressio sion n wi!! wi!! be passed as moca_ar+n  wh where n is the the posi positi tion on of the the functi function on argument argument starti starting ng with 1. 09999>G, MOCA wi!! eecute the ser(er ser(er comman command d ?toHch ?toHchar ar where where mocaHf mocaHfarg arg1 1  10 and mocaHfarg2  J09999>@.

31

T ) E

M O C A

E N G I N E

E:0eptions  As state stated d ear!ie ear!ierr, a!! of the commands commands,, pipes, pipes, and trigg triggers ers in a seBuence of commands must successfu!!$ eecute or a!! of it wi!! be ro!! ro!!ed ed bac. bac. here here is a wa$ wa$ to o(er o(errid ride e this this beha(io beha(iorr. If  fai!ure of a component or )/ ca!! can be considered norma! in some circumstances, there is a wa$ to te!! MOCA to not abort the curr curren entt runn runnin ing g seBu seBuen ence ce of comma command nds. s. o do this, this, it is necessar$ to catch the error error. his is done with either a trycatch statement or a catch c!ause. catch c!ause. tr&  /  / commandse1uence  commandse1uence  catcF catcFe*pr G ` commandse1uence commandse1uence    E catcF catcFe*pr G ` commandse1uence   /na$$& ` commandse1uence  N or command or command or {commandse1uence} catcF catcFe*pr ,e*pr9 ,e*pr9NG NG  A tr$'ca tr$'catch tch statem statement ent can be used used to eecut eecute e a diere dierent nt command seBuence for each error error condition that occurs. occurs. At !east one catch b!oc b!oc must be speci"ed. speci"ed. An optiona! "na!!$ b!oc b!oc can be spec speci" i"ed ed that that wi!! wi!! a!wa$ a!wa$s s be eec eecut uted ed,, rega regard rd!e !ess ss of an$ an$ success or error condition that occurs.  A catch catch c!ause c!ause can appear appear after after an$ comman command d or comman command d b!oc. b!oc. It can contain contain one or more more epression epressions s that de"ne de"ne the error error code code of the ecepti eception on that it wi!! catch. catch. -hen -hen an error error condition occurs, inc!uding a )/ error, eecution wi!! continue after the innermost innermost catch c!ause that catches the the eception. he specia! (ariab!e $: $: wi!!  wi!! then be set to the error code that caused the eception eception condition. condition. If no eception occurs, the $: $: (ariab!e  (ariab!e wi!! be set to 0 FeO\G. [update foo set Ear=@Ear,... where @*] catch$)%(>< if @N = $)%(> [insert into foo ...]

32

T ) E

M O C A

E N G I N E

E:e0ute a 0oa nd on a

Reote Coand E:e0ution It is a!so possib!e to perform commands on a remote MOCA  s$stem. s$stem. here wi!! wi!! be a !ater chapter chapter about about doing doing this and the imp! imp!ic icat atio ions ns of such such an in(o in(oca cati tion on.. he he s$nt s$nta a for doing doing a remote command is= re%ote system! system ! command F command F or "commandse1uence commandse1uence# #G he s$stem speci"ed in the parentheses is simp!$ an epression that must reso!(e reso!(e to a string string of the form= form= Uhostname=port Uhostname=portU. U. It can be a (ariab! (ariab!e e refer referenc ence, e, an en(iro en(ironme nment nt refer referenc ence, e, a Buoted Buoted string, or an$ other epression. -hen -hen the the MOCA MOCA ser( ser(er er enco encoun unte ters rs a remo remote te comm comman and, d, it init initia iate tes s a conn connec ecti tion on to the the MOCA MOCA ser( ser(er er spec speci" i"ed ed in the the spec speci" i"ed ed system. system. It then then passes passes the the command command For For comman command d seBuenceG seBuenceG to the the remote remote s$stem s$stem and waits for a response response.. he resu resu!t !ts s from from the the remo remote te s$st s$stem em beco become me the the resu resu!t !ts s of the the command. -hen a command is sent to a remote s$stem, the transaction is not commit committed ted automa automatic tica!! a!!$ $ on the remote remote s$stem. s$stem. It is !eft !eft unco uncommi mmitt tted ed,, and and furt furthe herr remo remote te comm comman ands ds to that that same same s$stem happen in the same commit contet as ear!ier commands. ncommitted data on the remote s$stem is a(ai!ab!e to the ca!!er  (ia furt further her remot remote e comma commands nds.. nfor nfortun tunate ate!$ !$,, the remot remote e s$ste s$stem m wi!! wi!! not not ha(e ha(e acce access ss to unco uncommi mmitt tted ed data data from from the the ca!!i ca!!ing ng s$stem, as it is not a fu!!$ distributed data access mechanism. One imp!ication is that it is possib!e to dead!oc $ourse!f using too man$ remote remote commands.
34

T ) E

M O C A

E N G I N E

E:e0ute a 0oa nd on utlple reote

!arallel Coand E:e0utio E:e0ution n It is a!so a!so poss possib ib!e !e to eec eecut ute e comm comman ands ds on mu!t mu!tip ip!e !e remo remote te MOCA s$stems in para!!e! using two s!ight!$ dierent beha(iors in regards regards to how transa transacti ctions ons are hand!e hand!ed. d. he s$nta s$nta for eecuting a command in para!!e! is= 9! command  command  F or "command para$$e$ system, system, 9! se1uence# se1uence#G 9! command F command F or "command inpara$$e$ system, system, 9! se1uence# se1uence#G he he s$s s$stems tems spe speci" ci"ed in the the par parenth enthes eses es are are sim simp!$ p!$ an epression that must reso!(e to a string of the form= Uhos Uhostn tnam ame= e=po port rt,, host hostna name me=p =por ort, t, EU. It can be a (ari (ariab ab!e !e refer referenc ence, e, an en(iro en(ironme nment nt refere reference nce,, a Buoted Buoted string string,, or an$ other epression. -hen -hen the the MOCA MOCA ser( ser(er er enco encoun unte ters rs a para para!!e !!e!! comm comman and, d, it initiates initiates a connection connection to each each MOCA ser(er ser(er speci"ed speci"ed.. It then passes the command For command seBuenceG to each remote s$stem s$stem and waits for a respon response. se. he resu!ts resu!ts of the command command contain the s$stem name, status of the command on that s$stem and the resu!t set for the eecution of the command on that s$stem. +ecause MOCA is simp!$ performing a set of remote eecutions in order to fu!!"! the para!!e! eecution reBuest, the same ru!es that app!$ to a remote eecution described in the section abo(e app!$ to para!!e! eecution with the eception of how commits are hand!ed. he he inpa inparra!!e a!!e!F !F G s$n s$nta ta eecu ecutted the the gi(e gi(en n comm comman and d or comm comman and d seBu seBuen ence ce ?in tran transa sact ctio ion@ n@.. he he ?in tran transa sact ctio ion@ n@ beha(ior is identica! identica! to the beha(ior of remote eecution. eecution. If an$ remote ser(er that taes p!ace in the para!!e! eecution dies, e(er$thing is ro!!ed bac.

35

T ) E

M O C A

E N G I N E

he para!!e!F G s$nta is s!ight!$ dierent. dierent. An$ errors errors that occur dur during ing the the remo remote te eec eecut utio ion n are, are, in eec eect, t, igno ignore red. d. he he transaction wi!! sti!! be committed on a!! other remote ser(ers as we!! as the !oca! ser(er ser(er.. he error error code for the remote remote ser(er that errored wi!! sti!! be returned in the status co!umn of the resu!t set, howe(er.

ritin= s0ripted 0oands @in Groov7 )ome )ometi time mes, s, !oca !oca!! s$nt s$nta a is not not Buit Buite e enou enough gh to acco accomp mp!is !ish h diicu!t diicu!t programmi programming ng tass. (en so, writing writing code code in C or a(a can be cumbersome cumbersome and error'pr error'prone. one. As an a!ternati(e, a!ternati(e, MOCA  has suppor supportt for script scripted ed compone components nts.. ecut ecuting ing a script scripted ed command is a usefu! a!ternati(e to the standard MOCA scripting !anguage. It a!!ows access access to a!! standard standard a(a c!asses and A&Is, which contain a rich set of tet processing, date processing, and regu! regu!ar ar epressi epression on hand!ing hand!ing capabi!i capabi!itie ties. s. In additi addition, on, a!! the standard MOCA a(a A&Is are a(ai!ab!e to scripted components to a!!o a!!ow w acce access ss to MOCA MOCA cont conte ett e!em e!emen ents ts,, eec eecut utio ion n of  commands, etc. o mae it easier to de(e!op scripts in MOCA, we>(e imp!emented our scripting capabi!it$ with the !anguage ;roovy  8 http=groo($.codehaus.org 7 http=groo($.codehaus.org 7.. 4roo($ is an open source scripting scripting !anguage that is based on a(a, and runs within the a(a *M. 4roo($ has acti(e de(e!opment and user communities, as we!! as etens etensi(e i(e tutori tutoria! a! and refer referenc ence e docume documenta ntatio tion n on their their web site. o in(oe in(oe a 4roo($ 4roo($ script script,, simp!$ simp!$ enc!os enc!ose e the script script code code in doub!ed sBuare bracets F?@ F?@ and ?NN@G. his does not not interfere with )/ eecution, as no )/ statement begins and ends with a sBuare bracet. Qere>s an eamp!e. eamp!e.  bin  #on$%to&trin$#on$%parse#on$he(, )*, + --

his simp!e eamp!e turns a base'1: number FheG into a base'2 number number FbinG. he command command can be eecuted eecuted in'!ine, in'!ine, or as part of a !arger command stream. M&.#/ select c he( from A- 0 1M&.#/  bin  #on$%to&trin$#on$%parse#on$he(, )*, + -- 0 1M&.#/ publish data where he(  2he( and bin  2bin 1M&.#/ 3

36

T ) E

M O C A

E N G I N E

4(ecutin$%%% &uccess5 he( 66666666 74A78449 );+79:79=

bin 66666666666666666666666666666666 )):)))):):):)):)):))))):))):)))) )):::::):)):))))):::::)::)):: )::)::)::::::::))::)))::)):::::: ):):):)):::::):::):))):))))))::)

< ?ows Affected M&.#/

#ote that the (ariab!es on the stac from the )/ statement were a(ai!ab!e a(ai!ab!e to the script. script. A!so, the (ariab!es (ariab!es created created in the scri script pt were were made made a(ai! a(ai!ab ab!e !e to down downst stre ream am comm command ands s Fe.g Fe.g.. pub!ish dataG. his is not the on!$ wa$ to produce output from a scripted command, though. here are four wa$s to aect the output of a script= 1. If the "na! "na! stateme statement nt in the script script resu!t resu!ts s in an object object of  t$pe t$pe Moca Moca%e %esu su!t !ts, s, the the resu resu!t !ts s obje object ct wi!! wi!! esse essent ntia! ia!!$ !$ o(er (erwrit write e a!! a!! other ther (ar (ariab! iab!es es that hat were ere used used in the the eecution of the script. 2. If the "na! "na! stateme statement nt in the script script resu!t resu!ts s in an object object of  t$pe Map, that map>s e$s wi!! be used as co!umn names, and the (a!ues (a!ues wi!! be used used as a sing!e sing!e row of data. data. his "ts in nice!$ with 4roo($>s s$nta for dec!aring maps in!ine in scripts. 8. If the "na! "na! statement statement is not not an object object of t$pe Moca% Moca%esu!ts esu!ts,, a!! a!! (ari (ariab! ab!es es that that were were crea create ted d in the the eec eecut utio ion n of the the script are made a(ai!ab!e Fin a sing!e rowG to downstream commands. here is no wa$ to mae a mu!ti'!ine mu!ti'!ine resu!t set with with this method. method. If $ou want want to ec!ude ec!ude a !oca! !oca! script script  (ariab  (ariab!e !e from from being being used used in this this wa$, wa$, dec!ar dec!are e it with with an underscor underscore e FHG as the "rst character character.. A!! (ariab!es (ariab!es of this form wi!! be ignored downstream. One One inte intere rest stin ing g issu issue e aris arises es with with the the spec speci" i"cs cs of the the 4roo($ !anguage. If a (ariab!e is ep!icit!$ dec!ared within the script Fe.g. with ?def (ar@ or ?type ? type (ar@G,  (ar@G, it wi!! not be made made a(ai!ab a(ai!ab!e !e downst downstre ream am,, outs outsid ide e the the scri script pt.. An$ An$  (ariab  (ariab!e !e that that is not not dec!ar dec!ared, ed, but is used, used, it it assu assumed med to be D0Q!G [[ def a = BR am CB

37

T ) E

M O C A

E N G I N E

def E = BR am OB *D0Q!G *D0Q!G ]] *D0Q!G H

7Secutin5... 0uccessL result $$$$$$ R am O  8ows Cffected> D0Q!G [[a = BR am CB *D0Q!G E = BR am OB *D0Q!G ]] *D0Q!G H 7Secutin5... 0uccessL a $$$$$$ R am C

E $$$$$$ R am O

 8ows Cffected> D0Q!G

]. If there there are no other other (ariab! (ariab!es es to put on the stac, stac, MOCA  MOCA  puts the (a!ue (a!ue of the !ast stateme statement nt onto the stac. stac. hat statement is interpreted in the same wa$ as the resu!t of a  a(a  a(a componen component. t. If it is a primit primiti(e i(e object object Fstri Fstring, ng, intege integerr, doub doub!e !eG, G, it wi!! wi!! be retu return rned ed as a sing sing!e !e co!u co!umn mn name named d ?resu!t@. he ear!ier command command cou!d ha(e been written as= select c he( from A- 0  #on$%to&trin$#on$%parse#on$he(, )*, + -- 0 publish data where he(  2he( and bin  2result

-hen eecuting scripting code, the engine maes the current Moca MocaCo Cont nte ett Fsee Fsee the the chap chapte terr on a(a a(a de(e de(e!o !opm pmen entG tG obje object ct a(ai!ab!e a(ai!ab!e as the bui!t'in bui!t'in (ariab!e (ariab!e named ?moca@. ?moca@. It is therefore therefore possib!e to in(oe commands and manipu!ate resu!ts from within a script.  import com%redprairie%moca%1 res  moca%e(ecuteInline"list user tables" res%addColumn"table@word", Mocaype%&?INB while res%ne(t  tablename  res%$et&trin$"table@name" &trin$ tableword  "" tablename%split"@"%each 

38

T ) E

M O C A

E N G I N E

word 6/ tableword D word%substrin$:,)%toEpperCase D word%substrin$)%to#owerCase F res%set&trin$Galue"table@word", tableword F resH --

39

M O C A

C O M M A N D

R E ! O S I T O R "  

C/apter 

#

41

T/e MOCA 0oa nd reposito r7

MOCA Coand Repositor7 This chapter provides a description o the  MOCA  MOCA com comman mand d repo reposito sitory ry!! he MOCA command repositor$ consists of "!es that contain the de"n de"nit itio ions ns for for comp compon onen entt !e(e !e(e!s !s,, comma command nds s and and trig trigge gers rs.. ogether, these de"nitions are used to determine what, how and when when to eec eecut ute e di dieren erentt comm comman ands ds.. Comp Compon onen entt !e(e !e(e!, !, comman command d and trigge triggerr de"niti de"nition on "!es are 3M/'ba 3M/'based sed.. heir heir content is de"ned in the fo!!owing sections.  *ers  *ersion ions s of MOCA MOCA prior prior to MOCA :.0 used a !egac$ !egac$ forma formatt for coponent coponent !e(e!, !e(e!, command command and trigger trigger de"nition de"nition "!es. "!es. A uti!it$ eists to con(ert de"nition "!es in the !egac$ format to the new 3M/' 3M/'ba base sed d form format at.. )imp )imp!$ !$ eec eecut ute e Jmco Jmcon( n(er ert> t> from from the the command !ine and an$ component !ibraries that are sti!! in the !egac$ !egac$ format wi!! be con(erte con(erted. d. Component Component !ibraries !ibraries that are are a!read$ in the new 3M/'based format wi!! not be aected.  Import  Important ant Note: Note: )upport for managed and simp!e managed component !ibraries are not $et supported, but are p!anned for the near future. herefore, a!! documentation documentation re!ating to managed and simp!e managed component !ibraries ma$ change when support is pro(ided.

42

M O C A

C O M M A N D

R E ! O S I T O R "  

Coponent &evel Definition 9iles Component !e(e! de"nition "!es are used to de"ne the dierent component component !ibraries !ibraries that that imp!ement imp!ement commands. commands. A component component !ibr !ibrar ar$ $ is noth nothin ing g more more than than a shar shared ed !ibr !ibrar ar$ $ or 6//, 6//, so a component !ibrar$ can on!$ imp!ement commands in !oca! s$nta and one other programming !anguage at a time.  A!! compo componen nentt !e(e! !e(e! de"nit de"nition ions s "!es "!es ha(e ha(e the the fo!!ow fo!!owing ing ru!es= ru!es= 

he "!ename must ha(e a ?.m!(!@ sui. Fe.g. MOCAbase.m!(!G



On!$ one component !e(e! de"nition is a!!owed per "!e.

C Coponent &ibraries

C component !ibraries can contain both C and simp!e C functions as we!! as as !oca! s$nta s$nta commands. C component !ibraries shou!d imp!emen ment the MOCAI CAIntia!iX a!iXe eFG, MOCA/ic /icenseFG and MOCA MOCA*ersio ersionFG nFG functio functions. ns. his is discus discussed sed further further in !ater !ater sections of this document. C functions return a pointer to a return structure containing an error code and resu!t set and simp!e C functions return a !ong specif$ing an error code. he fo!!owing is an eamp!e of the contents of the ?MOCA+ase@ component !ibrar$ de"nition "!e MOCA6I%srccmdsrcmocabase.m!(!= :component$levelG  :nameGMOCABase:HnameG  :descriptionG MOCA Base Component Library  :HdescriptionG :HdescriptionG  :sort$seTuenceG 0:Hsort$seTuenceG :Hcomponent$levelG

#ote that if the Z!ibrar$T e!ement is present, an$ component !ibrar$ can contain C functions as we!! as other component t$pes.

43

M O C A

C O M M A N D

R E ! O S I T O R "  

Mana=ed Coponent &ibraries

Manage Managed d compo componen nentt !ibrar !ibraries ies can contai contain n both both manage managed d and simp!e manage managed d methods methods as we!! as !oca! !oca! s$nta commands commands.. A  managed or simp!e managed method can be imp!emented in an$ !anguage supported b$ the Microsoft .# Common /anguage %untime. %untime. Managed Managed component component !ibraries !ibraries must must imp!ement imp!ement their c!asses within the namespace speci"ed in the component !e(e! de"n de"nit itio ion n "!e. "!e. A!so, A!so, mana manage ged d comp compon onen entt !ibr !ibrar arie ies s shou shou!d !d imp!ement a MOCA c!ass that eposes the Initia!iXeFG, /icenseFG and *ersionFG *ersionFG methods. his is discussed further further in !ater sections of this document. Managed methods return a return structure containing an error code and resu!t set and simp!e managed functions return a 82'bit integer specif$ing an error code. he he fo!! fo!!ow owing ing is an eam eamp! p!e e of the the cont conten ents ts of the the "cti "ctiti tiou ous s ?Managed)amp!e@ component !ibrar$ de"nition "!e /)6I%srccmdsrcmanagedsamp!e.m!(!= :component$levelG  :nameGMangedSample:HnameG  :descriptionG Sample Managed Methods:HdescriptionG  :sort$seTuenceG 10000:Hsort$seTuenceG  :namespaceG RedPrairie.ManagedSample:HnamespaceG :Hcomponent$levelG

COM Coponent &ibraries

COM component !ibraries can contain COM methods as we!! as !oca !oca!! s$nt s$nta a comm comman ands ds.. COM COM comp compon onen entt !ibr !ibrar arie ies s must must imp!ement their c!asses within the program id speci"ed in the component component !e(e! de"nitio de"nition n "!e. A!so, A!so, COM component component !ibraries !ibraries shou shou!d !d imp!e imp!eme ment nt the the Init Initia! ia!iX iXeF eFG, G, /ice /icens nseF eFGG and and *ersi ersion onFG FG meth method ods. s. his his is disc discus usse sed d furt furthe herr in !ate !aterr sect sectio ions ns of this document. COM methods return a resu!ts object containing an error code and resu!t set. he he fo!! fo!!ow owing ing is an eam eamp! p!e e of the the cont conten ents ts of the the "cti "ctiti tiou ous s ?COM)amp!e@ component !ibrar$ de"nition "!e /)6I%srccmdsrccomsamp!e.m!(!= :component$levelG

44

M O C A

C O M M A N D

R E ! O S I T O R "  

 :nameGCOMSample:HnameG  :descriptionG Sample COM Methods:HdescriptionG  :sort$seTuenceG 10000:Hsort$seTuenceG  :pro5ram$idG RedPrairie.COMSample:Hpro5ram$idG :Hcomponent$levelG

-ava Coponent &ibraries

 a(a  a(a compo componen nentt !ibrar !ibraries ies consis consistt of a a(a a(a pac pacage age.. Compon Component ents s in a ja(a pacage can contain a(a methods as we!! as !oca! s$nta commands. a(a component component !ibraries can contain contain c!asses within the pacage speci"ed in the component !e(e! de"nition "!e. In addition, addition, MOCA !oos !oos for a Component/ Component/ibrar ibrar$ $ c!ass in the pacage pacage named in the compone component nt !e(e! de"nitio de"nition n "!e. -ith that that c!as c!ass, s, a a(a a(a comp compon onen entt !ibr !ibrar ar$ $ can can perf perfor orm m !ibr !ibrar ar$ $ initia!iXation as we!! as pro(ide (ersion and !icense information to MOCA MOCA.. his his is disc discus usse sed d furt furthe herr in !ate !aterr sect sectio ions ns of this this document. COM methods return a resu!ts object containing an error code and resu!t set. he he fo!! fo!!ow owing ing is an eam eamp! p!e e of the the cont conten ents ts of the the "cti "ctiti tiou ous s ?COM)amp!e@ component !ibrar$ de"nition "!e /)6I%srccmdsrccomsamp!e.m!(!= :component$levelG  :nameGJavaSample:HnameG  :descriptionG Sample Java Methods:HdescriptionG  :sort$seTuenceG 10000:Hsort$seTuenceG  :pac3a5eG om.redprairie.les.!avasample:Hpac3a5eG :Hcomponent$levelG

Usin= Multiple Coponent T7pes

It is possib!e to de(e!op component !ibraries that can house C,  a(a,  a(a, and COM !ibrar !ibraries ies a!! at once. once. If the compon component ent !e(e! !e(e! contai ntains ns the the Z!ibr !ibrar ar$T $T e!eme !ement nt,, the the !e(e !e(e!! can cont contai ain n C compo componen nents ts as we!! we!! as a(a a(a COM and manage managed d compo componen nents. ts. Ifthe Z!ibrar$T e!ement is not present, the presence ZpacageT or ZnamespaceT or Zprogram'idT e!ements wi!! indicate that this !ibrar$ is not a C !ibrar$ and the s$stem wi!! not attempt to !oad a 6//.

45

M O C A

C O M M A N D

R E ! O S I T O R "  

BM& Eleent Des0riptions

he fo!!owing !ist describes each 3M/ e!ement that can eist in a component !e(e! de"nition "!e=  Elemen  Elementt name description

Descri Descripti ption on

he name of this component !e(e!. A component !e(e! name is reBuired  A descri descripti ption on of this this compon component ent !e(e!. !e(e!. component !e(e! description is optiona!.

A 

liErary

he he shar shared ed !ibr !ibrar ar$ $ or 6// 6// name name,, minu minus s the the "!ename etension. If a !ibrar$ is not pro(ided, pro(ided, the component component !ibrar$ name wi!! be used. #ote that hat if Z!ib Z!ibrrar$T ar$T is not not speci peci" "ed, ed, and and the component !e(e! speci"es a a(a pacage, COM program I6, or Managed .# namespace, no 6// wi!! be !oaded, and an$ de"ned C components wi!! not be eecuted.

directory

he sub direct director or$ $ name name that that this this compon component ent !e(e !e(e!> !>s s comm command and and and trig trigge gerr de"n de"nit itio ion n "!es "!es resi reside de in. If a dire direct ctor or$ $ isn> isn>tt pro(id pro(ided ed,, the the "!ename of this component !e(e! de"nition "!e, minus the ?.m!(!@ etension, wi!! be used.

sort$ seTuence

he he sort sort seBu seBuen ence ce of this this compo compone nent nt !e(e !e(e!. !. Compon Component ent !e(e!s !e(e!s with with higher higher sort sort seBuen seBuences ces tae tae preced precedenc ence e o(er o(er compo componen nentt !e(e!s !e(e!s with with !ower sort seBuence seBuence numbers. numbers. A sort sort seBuence seBuence is reBuired.

namespace

he name namesp spac ace e this this compon mponen entt !ibr !ibrar ar$> $>s s managed methods methods reside in. his is reBuired reBuired for compo componen nentt !ibrar !ibraries ies that that imp!em imp!ement ent manage managed d and simp!e simp!e managed managed methods. methods. It shou!d shou!d not be pro pro(ide (ided d for for an$ an$ othe otherr t$pe t$pe of comp compon onen entt !ibrar$.

pro5ram$id

he program id this component !ibrar$>s COM methods hods reside in. his his is reBuired for comp compon onen entt !ibr !ibrar arie ies s that that imp! imp!em emen entt COM COM meth method ods. s. It shou! shou!d d not not be pro( pro(id ided ed for an$ an$

46

M O C A

C O M M A N D

R E ! O S I T O R "  

other t$pe of component !ibrar$. pac3a5e

he pacag pacage e where where this this compon component ent !ibrar !ibrar$>s $>s  a(a  a(a compo componen nentt c!as c!asses ses resid reside. e. It is is reBu reBuire ired d for for compo mponent nent !ibr !ibrar arie ies s that that imp! imp!e ement ment a(a a(a methods. It shou!d not be pro(ided for an$ other t$pe of component !ibrar$.

read$only

 A Pag specif specif$in $ing g whethe whetherr this this compo componen nentt !e(e! !e(e! de"ni e"nittion ion "!e or an$ an$ of its its comm comman ands ds and and trig trigge gers rs can can be chan change ged d (ia the the cmd! cmd!ib ib A&I. A&I.  *a!i  *a!id d (a!ues (a!ues are ?$es@ ?$es@ and ?no@. ?no@. he defau!t defau!t  (a!ue  (a!ue is ?no@. ?no@.

version

he (ersio (ersion n of this this compon component ent !e(e! !e(e! de"nti de"ntion on "!e. "!e. his is optiona optiona!! and can be as as a container container for a re(ision contro! s$stem id or (ersion.

Coand Definition 9iles Comm Comman and d de" de"niti nition on "!es !es are are used used to de" de"ne the the di dieren erentt commands that mae up a component component !ibrar$. !ibrar$. MOCA current!$ suppor supports ts se(en se(en diere dierent nt t$pes t$pes of comman commands= ds= !oca! !oca! s$nta, s$nta, C func functi tion ons, s, simp simp!e !e C func functi tion ons, s, mana manage ged d meth metho ods, ds, simp simp!e !e managed methods COM methods, and a(a methods.  A!! comman command d de"nit de"nition ion "!es "!es shou!d shou!d reside reside in a direc director tor$ $ at the same !e(e! as the component !e(e! de"nition "!e and are named with the name of the component !e(e! de"nition "!e, minus the ?.m!(!@ etension.  A!! comman command d de" de"nit nition ions s "!es "!es ha(e ha(e the the fo!!ow fo!!owing ing ru!es= ru!es= 

he "!ename must picHin(entor$.mcmdG

ha(e



On!$ one command de"nition is a!!owed per "!e.

47

a

?.mcmd@

sui.

Fe.g.

M O C A

C O M M A N D

R E ! O S I T O R "  

&o0al S7nta: Coands

/oca! s$nta commands are distinguished b$ a ?t$pe@ e!ement with a (a!ue of ?/oca! )$nta@. he fo!!ow fo!!owing ing is the conten contents ts of the ?!ist adjust adjusted ed in(ent in(entor or$@ $@ -Md command, which is de"ned in 6C)6I%srccmdsrcdcsint!istHadjustedHin(entor$ 6C)6I%srccmdsr cdcsint!istHadjustedHin(entor$.mcmd= .mcmd= :commandG  :nameGlist appointment limits:HnameG  :descriptionG "his ommand is #sed to list entries in the appointment limits table.

 :HdescriptionG  :insecureG no:HinsecureG  :typeGLoal Synta$  :HtypeG :HtypeG  :local$syntaSG %selet 'rom )here and and order

& appt(limit *+start(tim,date *+end(tim,date *& by areod- start(dayod- start(tim

 :Hlocal$syntaSG  :ar5ument name= start(tim   alias= start(time   datatype= string     default$value= 1/001010000   reTuired= yesG 0tart time.  :Har5umentG  :ar5ument name= end(tim   alias= end(time   datatype= string     default$value= ////01010000   reTuired= yesG Start time.

 :Har5umentG :HcommandG

48

M O C A

C O M M A N D

R E ! O S I T O R "  

C and Siple C 9un0tions

C and simp!e C functions are distinguished b$ a ?t$pe@ e!ement with a (a!ue of ?C
 :Har5umentG :HcommandG

Mana=ed and Siple Mana=ed Met/ods

Managed and simp!e managed methods are distinguished b$ a ?t$pe@ e!ement with a (a!ue of ?Managed Method@ or ?)imp!e Managed Method@. he fo!!owing is the contents of the "cticious ?"nd fastest route@ user command, which is de"ned in /)6I%srccmdsrcusrint"ndHfastestHroute.mcmd= :commandG  :nameG'ind 'astest ro#te:HnameG  :descriptionG ind the 'astest ro#te 'rom one loation to another.

 :HdescriptionG  :typeGManaged Method  :HtypeG :HtypeG  :methodGusr;ind;astest8oute  :methodGusr;ind;astest8oute :HmethodG  :ar5ument name= startlo   alias= start(loation datatype = string  G G Starting loation.

 :Har5umentG  :ar5ument name= endlo   alias= end(loation datatype = string  G G 5nding loation.

 :Har5umentG :HcommandG

49

M O C A

C O M M A N D

R E ! O S I T O R "  

COM Met/ods

COM methods are distinguished b$ a ?t$pe@ e!ement with a (a!ue of ?COM Method@. he he fo!!o fo!!owin wing g is the the cont conten ents ts of the the "cti "ctici ciou ous s ?sca ?scan n seri seria! a! number@ user command, which is de"ned in /)6I%srccmdsrcusrintscanHseria!Hnumber /)6I%srccmdsrc usrintscanHseria!Hnumber.mcmd= .mcmd= :commandG  :nameGsan serial n#mber  :HnameG :HnameG  :descriptionG San a prod#t6s serial n#mber.:HdescriptionG  :typeGCOM Method  :HtypeG :HtypeG  :methodG #srSanSerial7#mber  :HfunctionG :HfunctionG  :ar5ument name= #srid     alias= #ser(id   datatype = string  G G User id.  :Har5umentG :HcommandG

-ava Met/ods

 a(a  a(a method methods s are dist disting inguis uished hed b$ b$ a ?t$pe@ ?t$pe@ e!eme e!ement nt with with a (a!ue (a!ue of ?a(a ?a(a Method@. Method@. he$ he$ are a!so the on!$ on!$ command command t$pe that that must inc!ude Zc!assT e!ement. he fo!!owing is the contents of the "cticious ?ca!cu!ate ucc12 chec digit@ user command, which is de"ned in /)6I%srccmdsrcusrja(aca!cu!ateHucc12HchecHdigit.mcm d= :commandG  :nameGal#late #189 he: digit:HnameG  :descriptionG Cal#late a #;189 he: digit.:HdescriptionG  :typeGJava Method  :HtypeG :HtypeG  :classGUcc'-Utils:HclassG  :methodG al#lateChe:
50

M O C A

C O M M A N D

R E ! O S I T O R "  

BM& Eleent Des0riptions

he fo!!owing !ist describes each 3M/ e!ement that can eist in a command de"nition "!e=  Elemen  Elementt name description

Descri Descripti ption on

he name of this component component !e(e! name is reBuired

!e(e!.

 A descri descripti ption on of this this compo componen nentt !e(e!. !e(e!. component !e(e! description is optiona!.

A  A 

type

he t$pe t$pe of command command this this is. *a!id command command t$pes are ?/oca! )$nta@, ?C
local$syntaS

he !oca! s$nt $nta that this command and wi!! i!! eecute. /oca! s$nta is reBuire ired for comma commands nds imp!em imp!ement ented ed b$ !oca! !oca! s$nta s$nta,, but shou!d not be pro(ided for an$ other t$pe of  command.

function

he name of the C functi function on that that imp!em imp!ement ents s this command. command. A function function name is reBuired reBuired for commands imp!emented b$ a C function, but shou!d not be pro(ided for an$ other t$pe of  command.

class

method

he name of the a(a c!ass that imp!ements this command. command. he c!ass c!ass is assumed assumed to be !ocated !ocated in the the paca acage ge name named d in this his comm comman and> d>s s component !ibrar$. !ibrar$. his e!ement is reBuired reBuired for  a(a  a(a method methods, s, but shou!d shou!d not be pro(id pro(ided ed for for an$ other t$pe of command. he name name of the the man managed aged,, COM, COM, or a(a a(a meth method od that that imp!e imp!eme ment nts s this comm comman and. d. A  method hod name is reBuire ired for commands imp! imp!em emen ente ted d b$ a mana manage ged, d, COM COM or a(a a(a meth method od,, but but shou shou!d !d not not be pro( pro(id ided ed for for an$ an$ other t$pe of command.

51

M O C A

C O M M A N D

R E ! O S I T O R "  

insecure

 A Pag Pag specif specif$ing $ing whethe whetherr this this is insecu insecure. re. Insecure commands can be eecuted e(en if the user user has not !ogged !ogged in $et. $et. *a!id (a!ues (a!ues are are ?$es@ and ?no@. he defau!t (a!ue is ?no@. ?no@.

disaEle

 A Pag Pag specif specif$ing $ing whethe whetherr this this shou!d shou!d be disab!ed. *a!id (a!ues are ?$es@ and ?no@. he defau!t (a!ue is ?no@.

ar5ument

One One e!eme e!ement nt per per de"ne de"ned d argum argumen ent. t. ach ach argument e!ement contains "(e attributes that descr describe ibe the argume argument, nt, which which are descri described bed be!ow. (er$ argume ument to commands imp!emented b$ C functions and managed and COM COM meth method ods s are are reBu reBuir ired ed to be de" de"ned. ned. Commands Commands imp!emented imp!emented b$ !oca! s$nta do not reBui eBuire re argu argume ment nts s to be de"n de"ned ed,, and and an$ an$ arguments that are de"ned are for documentation purposes on!$.  Attrib  Attribute ute

name

Descri Descripti ption on

he he name name of this this argu argume ment nt..  An argume argument nt name name is reBuired.

alias

he a!ias of this argument. An argument a!ias is optiona!.

default$value

he defau!t (a!ue of this argument to pass to the imp!ementation of the command if one is not pro(ide pro(ided. d. A defau! defau!tt (a!ue (a!ue is optiona!.

datatype

he datat$pe of this argument.  *a!id  *a!id datat$ datat$pes pes are ?integ ?integer@ er@,, ?Poa ?Poat@ t@,, ?str ?strin ing@ g@,, ?poi ?point nter er@ @ ?objec ?object@ t@ ?Pag@ ?Pag@ and ?resu!t ?resu!ts@. s@.  A data datat$p t$pe e is is reBu reBuire ired. d.

reTuired

 A Pag Pag specif specif$ing $ing whether whether this this argu argume ment nt is reBu reBuir ired ed.. he he

52

M O C A

C O M M A N D

R E ! O S I T O R "  

defau!t (a!ue is ?no@. read$only

 A Pag Pag specif specif$ing $ing whethe whetherr this this comman command d de" de"niti nition on "!e or an$ an$ of its its comm comman ands ds and and trig trigge gers rs can can be chan change ged d (ia (ia the the cmd! cmd!ib ib A&I. A&I.  *a!id  *a!id (a!ues (a!ues are ?$es@ ?$es@ and ?no@. ?no@. he defau!t defau!t  (a!ue  (a!ue is ?no@. ?no@.

documentatio n

 A tree tree of chi!d chi!d 3M/ 3M/ e!emen e!ements ts that that doc docume ument nt the the command. command. )ee the ?6ocumentin ?6ocumenting g Commands Commands and riggers@ section be!ow for more information.

version

he he (ers (ersio ion n of this this comm comman and d de"n de"nit itio ion n "!e. "!e. his is optiona! and can be as a container for a re(ision contro! s$stem id or (ersion. ( ersion.

53

M O C A

C O M M A N D

R E ! O S I T O R "  

Tri==er Tr i==er Definition 9iles rigger de"nition "!es are used to de"ne the imp!ementation of  triggers that ma$ reside within a component !ibrar$ as we!! as to disab!e and enab!e the imp!ementation of triggers that eist at !ower !e(e!s.  A!! trigge triggerr de"ni de"nitio tion n "!es "!es shou shou!d !d resi reside de in in a dire directo ctor$ r$ at at the the same same !e(e! as the component !e(e! de"nition "!e and are named with the name of the component !e(e! de"nition "!e, minus the ?.m!(!@ etension.  A!! trigge triggerr de" de"nit nition ions s "!es "!es ha(e ha(e the the fo!!ow fo!!owing ing ru!es= ru!es= 

he "!ename shou!d be named with the name of the command the trigger "res on and the name of the trigger itse!f and must ha(e a ?.mtrg@ sui and shou!d. Fe.g. scanHseria!Hnumer'm$Htrigger.mtrgG



On!$ one trigger de"nition is a!!owed per "!e.

Tri==er Ipleentation Definition

he fo!!owing is the contents of the "ctitious ?m$ trigger@ user trigger, which is de"ned in /)6I%srccmdsrc(arintscanHseria!Hnumber'm$Htr /)6I%srccmdsrc (arintscanHseria!Hnumber'm$Htrigger igger.mtrg .mtrg trigger de"nition "!e= :tri55erG  :nameGmy trigger  :HnameG :HnameG  :on$commandG san serial n#mber  :Hon$command :Hon$command G  :descriptionG "his is a trigger on the san serial n#mber ommand 

:HdescriptionG  :local$syntaSG log sanned serial n#mber )here *+serial(n#mber 

:Hlocal$syntaSG  :fire$seTuenceG 100:Hfire$seTuenceG :Htri55erG

54

M O C A

C O M M A N D

R E ! O S I T O R "  

Tri==er Disable Definition

he fo!!owing is the contents of the "ctitious ?m$ trigger@ disab!e trigger de"nition "!e, which is de"ned in /)6I%srccmdsrcusrintscanHseria!Hnumber'm$Htr /)6I%srccmdsrc usrintscanHseria!Hnumber'm$Htrigger igger.mtrg= .mtrg= :tri55erG  :nameGmy trigger  :HnameG :HnameG  :on$command G san serial n#mber  :Hon$command :Hon$command G  :disaEleG yes:HdisaEleG :Htri55erG

Tri==er Enable Definition

he fo!!owing is the contents of the "ctitious ?m$ trigger@ enab!e trigger de"nition "!e, which is de"ned in /)6I%srccmdsrcusrint scanHseria!Hnumber' m$Htrigger.mtrg= :tri55erG  :nameGmy trigger  :HnameG :HnameG  :on$command G san serial n#mber  :Hon$command :Hon$command G  :enaEleG yes:HenaEleG :Htri55erG

55

M O C A

C O M M A N D

R E ! O S I T O R "  

BM& Eleent Des0riptions

he fo!!owing !ist describes each 3M/ e!ement that can eist in a trigger de"nition "!e=  Elemen  Elementt

Descri Descripti ption on

name

he name of this component component !e(e! name is reBuired

on$command

he command this trigger "res on.

description

!e(e!.

 A descri descripti ption on of this this compo componen nentt !e(e!. !e(e!. component !e(e! description is optiona!.

A 

A 

fire$ seTuence

he seBuence this trigger wi!! "re in if more than one trigger eists on the same command.

local$syntaS

he !oca! s$nt $nta that this command and wi!! i!! eecute. /oca! s$nta is reBuire ired for comma commands nds imp!em imp!ement ented ed b$ !oca! !oca! s$nta s$nta,, but shou!d not be pro(ided for an$ other t$pe of  command.

enaEle

 A Pag Pag specif specif$ing $ing whet whether her this this trig trigger ger shou shou!d !d be enab!ed. enab!ed. his e!ement e!ement shou!d shou!d on!$ be used to to enab!e triggers that ha( ha(e a!r a!read$ bee been disab! disab!ed. ed. If this e!eme e!ement nt is used, used, the ?name@ ?name@ and ?on'command@ e!ements are the on!$ other reBuired reBuired e!ements. e!ements. *a!id (a!ues (a!ues are ?$es@ ?$es@ and ?no@.

disaEle

 A Pag Pag specif specif$ing $ing whet whether her this this trig trigger ger shou shou!d !d be disab!ed. disab!ed. his e!ement e!ement shou!d shou!d on!$ on!$ be used used to disa isab!e triggers that hat ha(e a(e a!r a!read$ been enab!e enab!ed. d. If this this e!ement e!ement is used, used, the the ?name@ ?name@ and ?on'command@ e!ements are the on!$ other reBuired reBuired e!ements. e!ements. *a!id (a!ues (a!ues are ?$es@ ?$es@ and ?no@.

ar5ument

One One e!eme e!ement nt per per de"ne de"ned d argum argumen ent. t. ach ach argument e!ement contains "(e attributes that descr describe ibe the argume argument, nt, which which are descri described bed be!ow. be!ow. +ecause a!! triggers triggers are imp!emented imp!emented b$ !oca! s$nta, arguments are not reBuired to be

56

M O C A

C O M M A N D

R E ! O S I T O R "  

de"ned, and are on!$ used for documentation purposes.  Attrib  Attribute ute

name

Descri Descripti ption on

he he name name of this this argu argume ment nt..  An argume argument nt name name is reBuired.

alias

he a!ias of this argument. An argument a!ias is optiona!.

default$value

he defau!t (a!ue of this argument to pass to the imp!ementation of the command if one is not pro(ide pro(ided. d. A defau! defau!tt (a!ue (a!ue is optiona!.

datatype

he datat$pe of this argument.  *a!id  *a!id datat$ datat$pes pes are ?integ ?integer@ er@,, ?Poa ?Poat@ t@,, ?str ?strin ing@ g@,, ?poi ?point nter er@, @, ?object@, ?Pag@, and ?resu!ts@.  A data datat$p t$pe e is is reBu reBuire ired. d.

reTuired

 A Pag Pag specif specif$ing $ing whether whether this this argu argume ment nt is reBu reBuir ired ed.. he he defau!t (a!ue is ?no@.

read$only

 A Pag speci specif$i f$ing ng whethe whetherr this trigg trigger er de"nit de"nition ion "!e or an$ of its commands and triggers can be changed changed (ia the the cmd!ib cmd!ib A&I. *a!id (a!ues (a!ues are ?$es@ and ?no@. he defau!t (a!ue is ?no@. ?no@.

documentatio n

 A tree tree of chi!d chi!d 3M/ 3M/ e!emen e!ements ts that that doc docume ument nt the the command. command. )ee the ?6ocumentin ?6ocumenting g Commands Commands and riggers@ section be!ow for more information.

version

he (ersion of this trigger de"nition "!e. "!e. his is optiona! and can be as a container for a re(ision contro! s$stem id or (ersion.

57

M O C A

C O M M A N D

R E ! O S I T O R "  

Do0uentin= Coands and Tri==ers MOCA pro(ides the abi!it$ to document commands and triggers a!ongs a!ongside ide the actua! actua! comman command d and trigger trigger de"nit de"nition ions. s. he mbui mbui!d !d uti! uti!it it$ $ can can then then be used used to gene genera rate te QM/ QM/'b 'bas ased ed documentation for each command and trigger, inc!uding project' based etensions, from the de"nition "!e. he fo!!owing is an eamp!e of the ?!ist !ibrar$ (ersions@ MOCA  command, which is de"ned in MOCA6I%srccmdsrcmocabase!istH!ibrar$H(ersions.mcmd= :commandG  :nameGlist library versions:HnameG  :descriptionG List the versions o' omponent libraries.

 :HdescriptionG  :typeGC #ntion:HtypeG  :functionG moaListLibrary2ersions:HfunctionG  :insecureG yes:HinsecureG  :ar5ument name=B ategory  B datatype=B string  BG BG "he omponent level name o' the omponent library to get the version 'or.

 :Har5umentG  :documentationG   :remar3sG   :L[9#CVC[ "his ommand lists the versions o' the omponent libraries in the #rrent ommands memory 'ile.

]]G   :Hremar3sG   :retrowsG "he n#mber o' ro)s ret#rned is e=#al to the n#mber o' omponent libraries the installed prod#t ontains.

  :HretrowsG :retcol name=B ategory  B type=B string  BG BGCategory  :HretcolG :HretcolG :retcol name=B library(nameB type=B string  BG BG Library name

:HretcolG version> > type=Bstring  :retcol name=B version BG BGLibrary version:HretcolG :eSception value=B eO?  BG BG "he ommand ompleted s#ess'#lly.

  :HeSceptionG :seealso cref= list ommandsHG  :HdocumentationG :HcommandG

58

M O C A

C O M M A N D

R E ! O S I T O R "  

BM& Eleent Des0riptions

he fo!!owing !ist describes each 3M/ e!ement that can eist in the docume documenta ntatio tion n sectio section n of comman command d and trigge triggerr de"nit de"nition ion "!es=  Elemen  Elementt

Descrip Descriptio tion n

private

6ocu 6ocume ment nt that that this this comm comman and d or trig trigge gerr is pri(ate to this component !ibrar$ and shou!d not be referenced b$ an$ other commands.

remar3s

6ocument a detai!ed !ed ep!anat anatio ion n of this his command command or trigger. In this section, section, it is often often necess necessar$ ar$ to inc!ud inc!ude e QM/ QM/ marup marup to format format the tet appropriate appropriate!$ !$.. se the C6AA C6AA tag for that purpose. purpose. If no C6AA C6AA region is speci"ed, speci"ed, then the tet is treated the same as it is in an$ other section.

retrows

 A descr descript iption ion of this this compon component ent !e(e!. !e(e!. component !e(e! description is optiona!.

A 

retcol

he seBuence this trigger wi!! "re in if more than one trigger eists on the same command.

eSception

One e!ement per eception the imp!ementation of this this comman command d is capa capab! b!e e of rais raisin ing. g. ach ach eception e!ement contains a sing!e attribute.

policy

 Attrib  Attribute ute

Descri Descripti ption on

value

he name of this argument. An argument name is reBuired.

One e!ement per po!ic !ic$ that dictates the beha(ior of of this command. ach po!ic$ e!ement e!ement can contain the fo!!owing se(en attributes.  Attrib  Attribute ute

Descri Descripti ption on

polcod

Code for this po!ic$.

polvar

 *ari  *ariab!e ab!e for this this po!ic po!ic$ $.

59

M O C A

C O M M A N D

R E ! O S I T O R "  

polval

 *a!u  *a!ue e for for this this po!i po!ic$ c$..

rtnum

%eturn number 1 for this po!ic$.

rtnum'

%eturn number 1 for this po!ic$.

rtflt

%eturn Poat number 1 for this po!ic$.

rtflt'

%eturn Poat number 1 for this po!ic$.

rtstr

%eturn string 1 for this po!ic$.

rtstr'

%eturn string 1 for this po!ic$.

eSample

One e!ement per eamp!e of code that $ou wish to document.

called$Ey

One e!ement per command that this command is ca!!ed ca!!ed b$. b$. ach ach ca!!ed'b ca!!ed'b$ $ e!ement e!ement contain contains s a sing!e attribute.

seealso

 Attrib  Attribute ute

Descri Descripti ption on

cref

he he name ame of comm mma and that that ca!!s this command.

One e!ement per command being referenced.  Attrib  Attribute ute

Descri Descripti ption on

cref

he name reference.

60

of

command

to

M O C A

C O M M A N D

R E ! O S I T O R "  

Initialiin= Coponent &ibraries )ometimes a component !ibrar$ ma$ reBuire some initia!iXation to occur before an$ functions or methods within the !ibrar$ can be ca!!ed. ca!!ed. Initia Initia!iXa !iXatio tion n ma$ in(o!(e in(o!(e registe registerin ring g app!ic app!icati ation on hoos or setting the (a!ues of g!oba! (ariab!es. MOCA MOCA supp suppor orts ts the the init initia ia!iX !iXat atio ion n of comp compon onen entt !ibra !ibrari ries es b$ specif$ing a function or method signature that a de(e!oper can imp!ement imp!ement when creating creating a component component !ibrar$ !ibrar$. -hen a ser(er process starts up, it ca!!s the initia!iXation function or method for each component component !ibrar$, !ibrar$, if one eists. eists. he initia!iXation function or meth method od shou shou!d !d retu return rn a 0 if it was was ab!e ab!e to succ succes essf sfu! u!!$ !$ initia!iXe itse!f and an error code if it wasn>t ab!e to successfu!!$ initia!iXe itse!f. itse!f. Component !ibraries !ibraries that cannot be successfu!!$ successfu!!$ init initia ia!iX !iXed ed wi!! wi!! not not be !oad !oaded ed and its its comm comman ands ds wi!! wi!! not not be a(ai!ab!e for eecution. C Coponent &ibraries

C compo componen nentt !ibrar !ibraries ies shou!d shou!d imp!eme imp!ement nt a MOCAIni MOCAInitia tia!iX !iXeFG eFG func functi tion on,, whic which h perf perfor orms ms an$ an$ reBu reBuir ired ed init initia ia!iX !iXati ation on of the the component !ibrar$ and returns an integer specif$ing whether or not the component !ibrar$ was initia!iXed in itia!iXed successfu!!$. successfu!!$. int D"9CRnitiali4evoid>  return % A

Mana=ed Coponent &ibraries

Managed component !ibraries shou!d imp!ement a MOCA MOCA.I .Ini niti tia! a!iX iXeF eFGG meth method od,, whic which h perf perfo orms rms an$ an$ reBu reBuir ired ed initia initia!iX !iXati ation on of the compon component ent !ibrar !ibrar$ $ and retur returns ns an intege integerr specif$ing whether or not the component !ibrar$ was initia!iXed successfu!!$. puElic class D"9C  puElic int Rnitiali4e >  return %< A A

COM Coponent &ibraries

COM component !ibraries shou!d imp!ement a MOCA.Initia!iXeFG meth method od,, whic which h perf perfor orms ms an$ an$ reBu reBuir ired ed init initia! ia!iX iXat atio ion n of the the

61

M O C A

C O M M A N D

R E ! O S I T O R "  

component !ibrar$ and returns an integer specif$ing whether or not the component !ibrar$ was initia!iXed in itia!iXed successfu!!$. successfu!!$. puElic class D"9C  puElic int Rnitiali4e >  return %< A A

62

M O C A

C O M M A N D

R E ! O S I T O R "  

&i0ensin= Coponent &ibraries MOCA MOCA supp suppor orts ts the the !ice !icens nsin ing g of comp compon onen entt !ibr !ibrar arie ies s b$ specif$ing a function or method signature that a de(e!oper can imp!ement imp!ement when creating creating a component component !ibrar$ !ibrar$. -hen a ser(er process starts up, it ca!!s the !icense function or method for each component !ibrar$, !ibrar$, if one eists. he !icense function or or method shou! hou!d d retur eturn n the the pro produc duct name ame the the compo mponent nent !ibr !ibrar ar$ $ imp!ements, which wi!! be checed against the !ist of !icensed products in the MOCA registr$ registr$.. Component !ibraries that do not not imp! imp!em emen entt a !ice !icens nse e func functi tion on are are auto automa mati tica ca!! !!$ $ cons consid ider ered ed !ice !icens nsed ed.. Comp Compon onen entt !ibr !ibrar arie ies s that that cann cannot ot be succ succes essf sfu! u!!$ !$ !ice !icens nsed ed wi!! wi!! not not be !oad !oaded ed and and its its comm comman ands ds wi!! wi!! not not be a(ai!ab!e for eecution. C Coponent &ibraries

C comp compon onen entt !ibr !ibrar arie ies s must must imp! imp!em emen entt a MOCA MOCA/i /ice cens nseF eFGG function, which returns a string specif$ing the product name the component component !ibrar$ !ibrar$ imp!ements. imp!ements. his string string must match match one of  the product names in the !icense section of the MOCA registr$ in order for it to be !ega!!$ !icensed. char *D"9C!icensevoid>  return moca< A

Mana=ed Coponent &ibraries

Managed component !ibraries must imp!ement a MOCA./icenseFG method, which returns a string specif$ing the product product name the the component component !ibrar$ !ibrar$ imp!ement imp!ements. s. his string string must match one of the product names in the !icense section of  the MOCA registr$ in order for it to be !ega!!$ !icensed. puElic class D"9C  puElic strin5 !icense >  return moca< A A

COM Coponent &ibraries

COM compo componen nentt !ibrari !ibraries es must must imp!em imp!ement ent a MOCA./ MOCA./ice icense nseFG FG method, which returns a string specif$ing the product name the component component !ibrar$ !ibrar$ imp!ements. imp!ements. his string string must match match one of 

63

M O C A

C O M M A N D

R E ! O S I T O R "  

the product names in the !icense section of the MOCA registr$ in order for it to be !ega!!$ !icensed. puElic class D"9C  puElic strin5 !icense >  return moca< A A

64

M O C A

C O M M A N D

R E ! O S I T O R "  

*ersionin= *e rsionin= Coponent &ibraries MOCA MOCA supp suppor orts ts the the (er (ersion sionin ing g of comp compon onen entt !ibr !ibrar arie ies s b$ specif$ing a function or method signature that a de(e!oper can imp!ement imp!ement when creating creating a component component !ibrar$ !ibrar$. -hen a ser(er process starts up, it ca!!s the (ersion function or method for each comp compo onent nent !ibr !ibrar ar$ $, if one one eis eists ts,, and and stor stores es the the (ers (ersio ion n information information interna!!$ interna!!$.. he (ersion (ersion function or method method shou!d return the product (ersion the component !ibrar$ imp!ements. he ?!ist !ibrar$ (ersion@ command returns a !ist of component !ibraries !ibraries and their their (ersions (ersions.. Component Component !ibraries !ibraries that that do not imp!ement a (ersion function wi!! ha(e a (ersion of ?#one@. C Coponent &ibraries

C comp compon onen entt !ibr !ibrar arie ies s must must imp! imp!em emen entt a MOCA MOCA* *ersi ersion onFG FG func functi tion on,, whic which h retu return rns s a stri string ng spec specif if$i $ing ng the the compo compone nent nt !ibrar$>s (ersion. (ersion. his string is used b$ the ?!ist !ibrar$ (ersion@ (ersion@ command to pro(ide (ersion information. char *D"9CWersionvoid>  return K.%.%< A

Mana=ed Coponent &ibraries

Managed component !ibraries must imp!ement a MOCA.*ersionFG MOCA.*ersionFG meth method od,, whic which h retu return rns s a stri string ng spec specif if$i $ing ng the the comp compon onen entt !ibrar$>s (ersion. (ersion. his string is used b$ the ?!ist !ibrar$ (ersion@ (ersion@ command to pro(ide (ersion information. puElic class D"9C  puElic strin5 Wersion >  return K.%.%< A A

COM Coponent &ibraries

COM compon component ent !ibrari !ibraries es must must imp!em imp!ement ent a MOCA.* MOCA.*er ersio sionFG nFG meth method od,, whic which h retu return rns s a stri string ng spec specif if$i $ing ng the the comp compon onen entt !ibrar$>s (ersion. (ersion. his string is used b$ the ?!ist !ibrar$ (ersion@ (ersion@ command to pro(ide (ersion information. puElic class D"9C  puElic strin5 !icense >  return K.%.%< A A

65

M O C A

C O M M A N D

R E ! O S I T O R "  

Initialiin=> &i0ensin= and *ersionin= -ava Coponent &ibraries  a(a  a(a compon component ent !ibrari !ibraries es wor s!ight!$ s!ight!$ diere dierent! nt!$ $. A ja(a ja(a !ibrar$ !ibrar$ de(e!oper shou!d imp!ement a c!ass ca!!ed Component/ibrar$ in their their !ibrar$ !ibrar$ pacag pacage, e, with the sing!e sing!e method method initia!iX initia!iXe. e. hat hat sing!e method is used to initia!iXe the !ibrar$ and return (ersion and and !ice !icens nsin ing g info inform rmat atio ion. n. he he initi initia!i a!iXe Xe meth method od retu return rns s a com.redprairie.moca.Moca/ibInfo object, which contains (ersion and !icensing !icensing informati information on for MOCA to use. use.  return new Doca!iERnfoW780R"1, !R97107>< A A

66

M O C A

C O M M A N D

R E ! O S I T O R "  

67

M O C A

! R O C E S S E S  

C/apter 



69

C U S T O M I ( I N G

T ) E

M O C A

S E R * E R

T/e Conne0tion Mana=e r and Server !ro0ess

MOCA !ro0esses This chapter provides description o the  MOCA  MOCA pro proces cesses ses!! here here are two basic modu!es of MOCA < the MOCA Connection Connection Manager modu!e and the MOCA )er(er &rocess modu!e.

MOCA Conne0tion Mana=er  he he MOCA MOCA Conn Connec ecti tion on Mana Manage gerr Fmoc Fmocac acon onmg mgrG rG is the the main main modu!e responsib!e for managing inbound connection reBuests to the speci" speci"ed ed port. port. Connec Connectio tion n reBues reBuests ts can origi originat nate e from from  *isua  *isua!! +asic -indow -indows s c!ients, c!ients, %< termin termina!s a!s,, or an$ other other MOCA  MOCA  c!ient.
70

M O C A

! R O C E S S E S  

 TC  TCPA"P

Client

  "  P   P  A   C    T

handle

     r      e      r      e      r      e      r      e     r      e      e      l      e      l      e      l      e      l      e      l      v      d      v      d      v      d      v      d     v      d      r      n      r      n      r      n      r      n     r      n      e     a      e     a      e     a      e     a     e     a       S      D      S      D      S      D      S      D       S      D

handle handle handle

Connection M a n a - e r 

   P    "    A    P    C     T

Client

    P     "     A     P    C     T

   e     p       i      P

    e     p        i       P

     e      p       i       P

     e      p        i        P

     e      p       i        P

Client   S e r v e r  Process

  S e r v e r  P ro c e s s

  S e r v e r  P rocess

  S e r v e r  P rocess

  S e r v e r  Process

Client

(er$ c!ient that connects to MOCA connects to the connection manager (ia C&I&. he connection manager maintains a socet hand hand!e !e for each conne connect cted ed c!ient c!ient.. -hen -hen a c!ie c!ient nt initiat initiates es a reBue reBuest, st, the connec connectio tion n manage managerr sees sees acti(i acti(it$ t$ on the socet socet hand!e and passes the c!ientLs hand!e to a ser(er process waiting in the poo!, spawning spawning a new ser(er ser(er process process if necessar$ necessar$. he ser(er process uses the hand!e to communicate the resu!ts of the reBuest bac to the c!ient direct!$.  TC  TCPA"P

Client

  "  P   P  A   C    T    P    "    A    P    C     T

Client

  y    r  o     P   t     "     A   n     P  e    C   v     T   n   i   t   s   i   l

handle

     r      e      r      e      r      e      r      e     r      e      e      l      e      l      e      l      e      l      e      l      v      d      v      d      v      d      v      d     v      d      r      n      r      n      r      n      r      n     r      n      e     a      e     a      e     a      e     a     e     a       S      D      S      D      S      D      S      D       S      D

handle handle handle

   P    P    a    a    s    s    s    s    D    D    a    a     n    n    d    d     l    e        el

   e     p       i      P

    e     p        i       P

     e      p       i       P

     e      p        i        P

Connection M a n a - e r 

     e      p       i        P

Client handle

 t s  l t s  R e s u

S e r v e r  P rocess

  S e r v e r  P ro c e s s

  S e r v e r  P rocess

  S e r v e r  P rocess

  S e r v e r  Process

Client

 After  After "nis "nishin hing g with with the c!ie c!ient nt hand!e hand!e,, the ser( ser(er er proc process ess send sends s it bac to the connection manager, which p!aces both the c!ient

71

M O C A

! R O C E S S E S  

hand!e and and the ser(er ser(er hand!e hand!e bac into its its poo! of hand!es hand!es.. +$ using this hand!e'passing techniBue, and b$ maing the ser(er process send resu!ts direct!$ to the c!ient, we a(oid maing the connectio connection n manager a data bott!en bott!enec. ec. #o actua! actua! data passes passes through the connection manager

72

M O C A

! R O C E S S E S  

MOCA Server !ro0ess Module he MOCA )er(er &rocess Fmocasr(prcG is the actua! woring modu!e of the MOCA pair. -hi!e the connection manager main!$ contro!s the number of ser(er processes and the traic sent to each of those ser(er processes, ser(er processes perform a!! of  the processing reBuested b$ c!ients. #orma!!$, there is a poo! of  ser(er processes responsib!e for processing a!! of the reBuests issued b$ c!ient app!ications. )er(er processes are responsib!e for the parsing of a!! commands recei(ed from c!ients, eecuting those commands, and returning resu!ts to c!ients. Qow commands are processed is determined b$ the information resident in the shared memor$ region that a ser(er process connects to. he he MOCA MOCA ser( ser(er er is prim primar ari! i!$ $ used used to proc proces ess s the the MOCA  MOCA  commands, which come in the form of MOCA'based protoco! on data stream from the socet connect passed to it from the MOCA  connection manager. manager. he MOCA ser(er process process can a!so process other stream protoco!s besides MOCA'based protoco! b$ de"ning a MOCA command. his MOCA command command wou!d be responsib!e for processing processing the data data stream stream on on the socet socet connect connection. ion. he MOCA command is de"ned in the MOCA registr$ Fi.e. ser(er' command under the connection manager con"gurationsG.

Confi=urin= MOCA he MOCA Connection Manager and MOCA )er(er &rocesses are con"gured b$ setting (a!ues in the MOCA registr$. On -indo indows ws p!at p!atfo form rms, s, the the MOCA MOCA regi regist str$ r$ is ept ept in the the -indo indows ws %egi %egist str$ r$ and and the the MOCA MOCAH H#* #*#A #AM M en(i en(iro ronm nmen entt  (ariab  (ariab!e !e is used used to deter determin mine e the instanc instance e name name within within the MOCA registr registr$ $ to use. If the MOCAH#* MOCAH#*#AM #AM is not not set, the ?6efau!t@ instance name wi!! be used instead. On #I3 p!atforms, the en(ironment (ariab!e MOCAH%4I)%W is used to point to a "!e that contains a!! the con" con"gur gurati ation on settings settings.. he MOCAH% MOCAH%4I) 4I)% %W W en(iro en(ironme nment nt  (ariab  (ariab!e !e is used used to deter determin mine e which which MOCA MOCA regist registr$ r$ "!e to use. use.

73

M O C A

! R O C E S S E S  

he MOCAH%4I)%W en(ironment (ariab!e must be set in order to start the connection manager.

74

M O C A

! R O C E S S E S  

T/e indo8s MOCA Re=istr7 he "rst page of the MOCA %egistr$ ditor disp!a$s a !ist of  eisting eisting MOCA instances. instances. Wou can change the con"gurat con"guration ion of  an inst instan ance ce b$ doub doub!e !e c!ic c!ici ing ng on an inst instan ance ce name name or b$ high!ighting an instance name and c!icing dit. Conne0tion Mana=er Confi=uration

his tab con"gures man$ of the the connection manager options. On #I3 #I3 s$s s$stems tems,, the the entri ntries es in this this sec section tion are are in the

75

M O C A

! R O C E S S E S  

CO#M4%N CO#M4%N section section of the registr$ registr$.. he ?Connection ?Connection Manager@ Manager@ tab contains the fo!!owing "e!ds= C&I& port number number that Ser,er! ort F#I3 "e!d= portG  he C&I& the connection connection manager !istens on for incoming connections. A   (a!ue  (a!ue is reBu reBuire ired d for for this this "e!d "e!d.. Conso$e! ort F#I3 ort F#I3 "e!d= conso!e'portG  he C&I& port number that the connection manager !istens on for incoming conso!e connections. connections. he defau!t is &ortS1. &ortS1. Conso$e! assword assword F#I3 "e!d= passwordG  he password for the the conne onnect ctio ion n man manage ager cons conso o!e. !e. he he defa defau! u!tt is UpasswordU. "e!d= ser(er'pr ser(er'program ogramGG  he name Ser,er! ro'ra% F#I3 "e!d= of the ser(er process that the connection manager spawns to hand!e incoming connections. his shou!d on!$ be changed if  comm comman and d !ine !ine opti option ons s need need to be pass passed ed to the the ser( ser(er er process. he defau!t is mocasr(prc. mocasr(prc. It is on!$ intended intended to be de"ned de"ned on the primar$ primar$ connectio connection n manager manager con"gurat con"gurations ions Fi.e. CO#M4% connection con"guration tabG. Ser,er! Ser,er! Co%%and Co%%and F#I3 F#I3 "e!d "e!d== ser( ser(er er'c 'com omma mand ndGG  he he MOCA command for the ser(er process to eecute when it needs to process data from an incomming data stream (erses processing the incoming data stream assuming it is using the MOCA'base MOCA'based d protoco!. protoco!. It is on!$ intended intended to to be de"ned de"ned on seco second ndar ar$ $ conn connec ectio tion n mana manage gerr con" con"gu gura rati tion ons s Fi.e Fi.e.. non non CO#M4% connection con"guration tabsectionG. Initia$ Initia$ Ser,ers! Ser,ers! F#I3 F#I3 "e!d= "e!d= initia! initia!'se 'ser(e r(ersG rsG  he initia initia!! numbe umberr of ser(e er(err pro processe esses s that that are are spaw pawned ned b$ the connection manager when it starts. starts. he defau!t is 7. Ma+ Ser,ers! Ser,ers! F#I3 F#I3 "e!d= "e!d= ma'se ma'ser(e r(ersG rsG  he maimu maimum m number of ser(er processes that can be running at one time. -hen a!! ser(er processes are bus$ and a new connection reBuest is recei(ed, the connection manager wi!! spawn a new ser(er process if the number of running ser(er processes is !ess !ess than than this this (a!ue. (a!ue. If the maimu maimum m numb number er of ser(e ser(err processes is a!read$ running, the new connection reBuest is Bueued Bueued up unti! a ser(er ser(er proces process s become becomes s a(ai!a a(ai!ab!e b!e.. his his feature he!ps to a(oid taing up massi(e resources when a

76

M O C A

! R O C E S S E S  

!arge number number of users users tr$ to connect connect at once. he defau!t defau!t is 100. F#I3 3 "e!d= e!d= ma ma'id! 'id!e' e's ser(e er(errsG  his his is the the Ma+ Ma+ Id$e Id$e F#I maimum number of id!e ser(er processes that are a!!owed to be running running at one time. time. he connect connection ion manager manager i!!s id!e id!e ser(er ser(er processe processes s if more than this this (a!ue are id!e. id!e. he idea! idea! Ma Ma Id!e Id!e (a!u (a!ue e is !arg !arge e enou enough gh to hand hand!e !e pea pea acti acti(i (it$ t$ reBuirements without undu!$ impacting id!e resource needs. he defau!t is 70. Ser,e Ser,er! r! Co%% Co%%and and Co)nt Co)nt F#I3 F#I3 "e!d= "e!d= ma'co ma'comma mmands ndsGG  he maimum number of commands that wi!! be processed b$ each ser(er process before it is rec$c!ed Fi.e. shut down and a new process process started started in its p!aceG. p!aceG. his approach approach wors wors in a simi!ar wa$ to the ser(er !ifetime propert$, but maes it !ess !ie!$ that a!! ser(er processes wi!! be shut down at the same time. time. )ettin )etting g this (a!ue (a!ue to 0 disab! disab!es es the comman command d !imit feature. he defau!t is 0 Fdisab!edG. Ser,er! Ser,er! ifeti%e F#I F#I3 3 "e!d "e!d== ser( ser(er er't 'tim imeo eout utGG  he he maimum !ifetime in hours that a ser(er process process is a!!owed to run. run. Once Once an hour hour the conne connect ctio ion n mana manage gerr i!! i!!s s ser( ser(er er proc proces esse ses s o!de o!derr than than this this (a!u (a!ue. e. 6ue 6ue to a timi timing ng race race condition condition within the connection connection manager manager,, a ser(er ser(er process process ma$ actua!!$ !i(e as !ong as one hour more than this (a!ue. his pro(ides a mechanism to c!eanup memor$ resources that are !eaed or used b$ components that perform Bueries that return return !arge resu!t resu!t sets. sets. )etting )etting this (a!ue to 0 disab!es disab!es the ser(er !ifetime !ifetime feature. he defau!t is is 0. C$ient 3i%eo)t F#I3 3i%eo)t F#I3 "e!d= c!ient'timeoutG  he maimum time time in seco second nds s a c!ie c!ient nt conn connec ecti tion on is a!!ow a!!ows s to be id!e id!e.. )ettin )etting g this this (a!ue (a!ue to 0 disab! disab!es es the c!ient c!ient timeou timeoutt featur feature. e. his option shou!d on!$ be use used if a !oa !oad'ba!anced con"guration is used. he defau!t (a!ue is 0. 0. Connection Con/)ration 3a*  3a*   he tab strip that appears at the bottom bottom of the the ?Connection Manager@ Manager@ tab. he primar$ connectio connection n manager manager con"gurat con"guration ion is named CO#M4% and cont contro ro!s !s the the main main conn connec ecti tion on mana manage gerr. Wou can can add add addi additi tion ona! a! conn connec ecti tion on mana manage gerr con" con"gu gura rati tion ons s for for othe otherr soc socet et conn connec ecti tion ons s $ou $ou wish wish to mana manage ge usin using g a MOCA  MOCA  command. command. A pop'up menu menu wi!! appear appear when $ou right'c right'c!ic  !ic 

77

M O C A

! R O C E S S E S  

on the tab strip. strip. he pop'up pop'up wi!! a!!ow $ou $ou to add or de!ete de!ete connectio connections ns con"gurat con"gurations. ions. #O= (er$ (er$ time $ou $ou add or de!ete a connection con"guration it creates and remo(es a corresponding tas de"nition named CO# O#M4 M4%H %HZc Zco onne nnectio ction nHnam Hname eT Fi.e Fi.e.. moca mocaco conm nmgr gr ) ZconnectionHnameTG.

78

M O C A

! R O C E S S E S  

Server !ro0ess Confi=uration

he (a!ues on this tab are used to con"gure the beha(ior of a!! ser(er ser(er processe processes. s. On #I3 s$stems, s$stems, the entries entries in this section section are in the )%*%N section of the registr$ "!e. he ?)er(er@ tab contains the fo!!owing "e!ds= 

Co%%ands! Me%or& i$e F#I3 "e!d= memor$'"!eG  he pathname of the stored command con"guration "!e.



Co%%ands! So)rce So)rce 4irectories 4irectories F#I3 "e!d= commands' commands' dirG  A semi'co!on separated F#I3= co!on'separatedG !ist of 

79

M O C A

! R O C E S S E S  

direc directo tori ries es that that cont contani anin n comma command nd de"n de"nit itio ion n "!es "!es.. he he mbui!d uti!it$ searches each director$ in the !ist for command de"nition "!es when bui!ding the memor$ "!e. 

'!ibrar$G  he he App$ication i*rar&  F#I3 "e!d= app'!i pathname of the 6// or shared !ibrar$ whose MOCAInitia!iXeF G function shou!d be ca!!ed when a ser(er ser(er process starts. his feature a!!ows app!ication hoos to be registered.

80

M O C A

! R O C E S S E S  

Database Confi=uration

he (a!ues on this tab are used to con"gure the database for the ser(er ser(er processe processes. s. On #I3 s$stems, s$stems, the entries entries in this section section are in the )%*%N section of the registr$ "!e. he ?6atabase@ tab contains the fo!!owing "e!ds= 

database engine the ser(er processes processes connect connect   En'ine  he database to. to.



  4ri,er F#I3 "e!d= db!ib  see be!owG  he database'speci"c dri(er the ser(er ser(er processes processes shou!d use.
81

M O C A

! R O C E S S E S  

database, it is possib!e to use either a nati(e or 6+C dri(er. he 6+C dri(er can be used to enab!e certain additiona! featur features es a(ai!a a(ai!ab!e b!e to compon component ents s writte written n in a(a. a(a. )ee the chapter on a(a de(e!opment for more m ore detai!s 

se OS A)tentication 


  ser F#I3 #I3 "e!d= e!d= dbuse buserG rG  he he use username name the the ser ser(er (er processes shou!d use to connect to the database.



  assword  assword  F#I3 "e!d= dbpassG  he password the ser(er processes shou!d use to connect to the database.



SA ser ser F#I F#I3 3 "e!d= e!d= dbau dbause serG rG  he he )A user userna name me the the Inst Insta! a!!) !)/ / uti! uti!it it$ $ shou shou!d !d use use to conn connec ectt to a )/ )/ )er( )er(er er database database when creatin creating g database database objects. objects. his "e!d "e!d is on!$  (isib!e  (isib!e if the the engi engine ne is )/ )/ )er(er )er(er..



SA asswor assword d F#I3 "e!d= dbapassG  he )A password the Inst Insta! a!!) !)/ / uti! uti!it it$ $ shou shou!d !d use use to conn connec ectt to a )/ )/ )er( )er(er er database database when creatin creating g database database objects. objects. his "e!d "e!d is on!$  (isib!e  (isib!e if the the engi engine ne is )/ )/ )er(er )er(er..



546C 4ri,er F#I3 "e!d= dbdri(erG  )peci"es the c!assname of the 6+C dri(er to be used for this this instance of MOCA. his must must be a fu!!$'B fu!!$'Bua! ua!i"e i"ed d c!assn c!assname ame.. s >s ?thin@ dri(er wou!d be orac!e.jdbc.Orac!e6ri(er, and the 6) Fopen sourceG 6+C dri(er (er for )/ ser(er wou!d be net.sourceforge.jtds.jdbc.6ri(er.



F#I3 "e!d= "e!d= dbconnG dbconnG  )peci" )peci"es es the %/ to be 546C 546C R R F#I3 gi(e i(en to the 6+C dri(e i(er when open pening a data atabase connection. he format of this %/ is dri(er'speci"c, and can be tai!ored to the needs of of each speci"c dri(er. dri(er. s ?thin@ dri(er has %/s of the form= jdbc=orac!e=thin= usernameNR usernameNRhostname hostname==port= port=instancename, instancename, whi!e )/ ser(er>s !oo !ie=  jdbc=j  jdbc=jtds tds=sB =sB!se !ser(e r(er= r= hostname hostname initialcatalo+ initialcatalo+NN

On #I3 s$stems, the responsibi!it$ for correct!$ specif$ing the dbdri( dbdri(er er,, dbconn dbconn,, and db!ib fa!!s fa!!s on the user. user. he -indow -indows s regis registr$ tr$ edito editorr a!!ows a!!ows for eas$ eas$ con" con"gur gurati ation on of popu!a popu!arr Fand Fand

82

M O C A

! R O C E S S E S  

!ega!G settings, but the ni side must be set up correct!$ in order for the s$stem to operate. operate. hese settings are= are= dblib

 A (a!id (a!id MOCA's MOCA'supp upp!ie !ied d !ibrar !ibrar$ $ that that imp!e imp!emen ments ts MOCA MOCA>s )/ )/ 6+ dri(er dri(er.. As of this this writing writing,, ther there e are are thre three e supported !ibr ibrar$ t$pes= Orac!e> !e>s OCI !ib !ibrar$, Microsoft>s A6O !ibrar$ F-indows on!$, on!$, for )/ ser(erG, and 6+C. 6+C. he 6+C'based 6+C'based dri(er dri(er is the most most Peib!e, Peib!e, a!!owi a!!owing ng access access to man$ man$ databa database se t$pes t$pes throug through h the use of (endor'supp!ied 6+C dri(ers.

dbdriver   A fu!!$'B fu!!$'Bua! ua!i"e i"ed d c!assn c!assname ame of a 6+C dri(er dri(er to be !oad !oaded ed b$ the the MOCA MOCA 6+C db!ib db!ib dri(e dri(err. he he !ega !ega!!  (a!ues  (a!ues of this this dri(er dri(er depend depend on the databa database se being being connected to, and the desired settings.

(a!id 6+C %/ for the 6+C dri(er dri(er speci" speci"ed ed under under dbconn  A (a!id the dbdri(er dbdri(er setting. setting. )ince 6+C a!!ows a!!ows for setting setting up of a number of dri(er'speci"c connection options in the %/, a comp!ete !isting of (a!id (a!ues of this "e!d is imposs impossib!e ib!e.. here here is another another MOCA MOCA docume document nt that desc descri ribe bes s our our supp suppor orte ted d data databa base ses, s, and and the the now nown n dri(ers and settings that wor with them.

83

M O C A

! R O C E S S E S  

Environent Confi=uration

he he en(i en(iro ronm nmen entt tab tab a!!o a!!ows ws en(i en(iro ronm nmen entt (ari (ariab ab!e !es s to be con"gured through through the registr$ registr$. -hen MOCA runs as a ser(ice under # Fmore on this !aterG, these (ariab!es are p!aced into the en(ironment of the the ser(ice tas. tas. -hen not running as a ser(ice, the (a!ues under this con"guration page are used when MOCA  processes !oo for en(ironment (ariab!es and the$ are not found in the actua! actua! running running en(ironment en(ironment.. he$ can be though thoughtt of as defau!t en(ironment (ariab!es.

84

M O C A

! R O C E S S E S  

#ote, though, that some en(ironment (ariab!es ha(e non'MOCA  s$stem imp!ications Fe.g. &AQG, and setting those (ariab!es in this screen does not ha(e the desired eect, ecept when MOCA  is runn runnin ing g as a ser( ser(ic ice, e, sinc since e that that is the the on$&   time that the  (ariab  (ariab!es !es !isted !isted here here are are p!ac p!aced ed into into a proces processes ses en(iro en(ironme nment. nt. On #I3 #I3 s$st s$stem ems, s, thes these e sett settin ings gs can be con" con"gu gure red d in the the registr$, under the #*I%O#M#N section of the registr$, but this capabi!it$ is rare!$ used, as the settings on!$ aect MOCA' contro!!ed processes, and on!$ if the$ access the en(ironment through the MOCA functions that pa$ attention to the registr$.  An$ proces process, s, e(en a MOCA MOCA process, process, that that accesses accesses the proces process>s s>s en(iro en(ironme nment nt direc direct!$ t!$,, wi!! wi!! not not see see these these settin settings. gs. Instea Instead, d, en(ironment (ariab!es that need to be set on a #I3 s$stem are t$pica!!$ set up through some other means, such as a startup script or pro"!e script.

85

M O C A

! R O C E S S E S  

Servi0e Confi=uration Confi=uration

he he ser( ser(ic ice e con" con"gu gura rati tion on tab tab is one one that that does does not not ha(e ha(e an$ an$ ana!og ana!og on #I3. #I3. he settings settings and and buttons buttons on this page page a!!ow a!!ow setting up MOCA to run as an # ser(ice. 

Command nd to run run throug through h the ser(i ser(ice ce.. he he   Co%%and ' Comma defau!t defau!t is to run the MOCA MOCA conne connecti ction on manage managerr. here here is a!mos a!mostt no reas reason on to set set o(er o(erri ride de this, this, as the the defa defau! u!tt wi!! wi!! usua!!$ do what $ou want.

86

M O C A

! R O C E S S E S  



%edire rect cts s the the outp output ut of the the conn connec ecti tion on   O)tp)t O)tp)t i$e i$e ' %edi mana manage gerr to a "!e. !e. his his is usef usefu! u! if $ouL $ouLrre runn runnin ing g the the connection manager with tracing enab!ed for some hard'to' "nd bug.



  4ependencies ' 4ependencies ' his a!!ows $ou to set up dependencies for the ser(ice. -ith this option option enab!ed, MOCA can be forced forced to star startt up after after anot anothe herr ser( ser(ic ice. e. his his is usef usefu! u! for for mai maing ng MOCA dependent on an Orac!e 6atabase, for instance, and the$ can both be made to automatica!!$ start up on s$stem boot.



  ' his is the de!a$ in seconds that the ser(ice Start 4e$a&  4e$a&  ' cont contro ro!! prog progra ram m wait waits s befo before re ic icin ing g o the the conn connec ecti tion on manager. manager. his is usefu! for situations where, e(en e(en though the depe depend nden entt ser( ser(ic ice e is a!re a!read ad$ $ star starte ted, d, itLs itLs not not read read$ $ for for connections $et. his has been nown to happen happen with Orac!e.



Insta$$ Ser,ice ' Ser,ice ' his button actua!!$ ca!!s out to the MOCA  )er(ice Contro! program and insta!!s the MOCA instance as a ser(ice, with the current options.



ninsta$$ Ser,ice ' Ser,ice ' his button remo(es the MOCA ser(ice from the !ist of ser(ices on the current # bo.



  Start Ser,ic Ser,ice e ' his his but button ton start arts the curre urrent nt MOCA  MOCA  instanceLs ser(ice. If the instance is not insta!!ed as a ser(ice, ser(ice, an error message is printed.



Stop Ser,ice ' Ser,ice ' his buton stops the current MOCA instanceLs ser(ice.

87

M O C A

! R O C E S S E S  

Tas Confi=uration

he MOCA connection manager can spawn non'worer tass as we!!. he "e!ds on this page a!!ow those tass tass to be con"gured. #O= as as de"nitions created as part of a connection con"gure, can can on!$ on!$ be de!e de!ete ted d b$ de!e de!eti ting ng the the conn connec ecti tion on mana manage gerr con"guration. 

3ask Na%e ' he name name of the the tas tas to be con" con"gu gure red. d. On #I3 #I3 s$st s$stem ems, s, this this is used used as the the regi regist str$ r$ sect sectio ion n unde underr which which a!! the other other "e!ds "e!ds reside reside.. .g. .g. if the tas is named named  "ic(Re  "ic(Relea leaseM seMana ana+er  +er , the section wou!d be

88

M O C A

! R O C E S S E S  

&IC\%/A)MA#A4%N. he !ist of tass is de"ned de"ned under the CO#M4%N CO#M4%N section, as the comma'sep comma'separate arated d "e!d tas( list. list. 

  E+ec)ta*$e F#I3 E+ec)ta*$e F#I3 "e!d= programG  he program to run as the tas.



  Ar')%ents F#I3 F#I3 "e!d= "e!d= argume arguments ntsGG  he command command !ine arguments to pass to the eecutab!e.



Start In F#I3 In F#I3 "e!d= start'inG  he director$ to start the tas  in.



O)tp)t i$e F#I3 i$e F#I3 "e!d= !og"!eG  he pathname of the "!e to direct output to.



A)to Start F#I3 Start F#I3 "e!d= autostartW#G  If this is checed, the the tas tas is auto automa mati tica ca!! !!$ $ star starte ted d when when the the conn connec ecti tion on manager is started.



A)to Restart F#I3 Restart F#I3 "e!d= respawnW#G' If this is checed, the tas tas is automa automatic tica!! a!!$ $ restar restarted ted when when it goes goes down. In genera genera!, !, this shou!d shou!d ne(er ne(er be checed checed.. If a tas tas dies, the the issue shou!d be reso!(ed instead.

89

M O C A

! R O C E S S E S  

-ob Confi=uration

he MOCA connection manager can spawn schedu!ed jobs as we!!. he "e!ds on this page a!!ow those jobs jobs to be con"gured. con"gured. 

5o* Na%e ' Na%e ' he name of the job to be con"gured. On #I3 s$stems, this is used as the registr$ section under which a!! the other "e!ds "e!ds reside. .g. if the job job is named CleanLo+s, CleanLo+s, the section section wou!d be C/A# C/A#/O4)N /O4)N.. he !ist of jobs jobs is de"ned de"ned under the CO#M4%N section, as the comma'separated "e!d  o#lis  o#listt.

90

M O C A

! R O C E S S E S  



  E+ec)ta*$e F#I3 E+ec)ta*$e F#I3 "e!d= programG he program to run as the job.



  Ar')%ents F#I3 F#I3 "e!d= "e!d= argume arguments ntsGG  he command command !ine arguments to pass to the eecutab!e.



Start In F#I3 In F#I3 "e!d= start'inG  he director$ to start the job in.



O)tp)t i$e F#I3 i$e F#I3 "e!d= !og"!eG  he pathname of the "!e to direct output to.



  Sced)$e F#I F#I3 3 "e!d "e!d== sche schedu du!e !eGG  he he sche schedu du!e !e in #I3 #I3 cron cronta tab b form format at for runn runnin ing g this this.. C!ic C!icin ing g on the !oo !ooup up butt button on with within in this this "e!d e!d brin brings gs up a form form to more more easi easi!$ !$ schedu!e the job.



4on7t R)n F#I3 R)n F#I3 "e!d= inhibitW#G  6on>t run this job at the the schedu schedu!e !ed d times. times. his his a!!ow a!!ows s a job job to be turne turned d o  temporari!$.

91

M O C A

! R O C E S S E S  

EMS Confi=uration

he M) )poo!er is a process that checs for pending M) e(ents and forwards forwards them to an M) ser(er ser(er.. On #I3 s$stems, the entries in this section are in the M)N section of the registr$ "!e. !e. he he "e!d "e!ds s on this this page page a!!o a!!ow w the the M) M) )poo )poo!e !err to be con"gured. 

  8ost  8ost  F#I3 "e!d= hostG  he hostname or I& address the M) ser(er is running on.

92

M O C A

! R O C E S S E S  



  ort F#I3 ort F#I3 "e!d= portG  he port number the M) ser(er is running on.



Spoo$ 4irector&  F#I3   F#I3 "e!d= spoo!'dirG  he director$ the M) )poo!er shou!d chec for pending M) e(ents to send to the M) ser(er.



F#I3 3 "e!d= "e!d= proc proces esse sed'd d'dir irGG  he he   rocessed rocessed 4irector&  4irector&  F#I director$ to mo(e M) e(ents to after sending them to the M) ser(er.



6ad 4irector&  F#I3  F#I3 "e!d= bad'dirG  he director$ to mo(e M) e(ents to after M) spoo!er fai!s to be sent to the M) ser(er.

93

M O C A

! R O C E S S E S  

Se0urit7 Confi=uration

MOCA can optiona!!$ run in a secure mode. hat means that that a!! users users wi!! ha(e to !og in and obtain obtain a securit$ securit$ session session e$. e$. he secu securi rit$ t$ mode mode!! is base based d on the the conc concep eptt of domains, domains, which is unre!at unre!ated ed to # domain domain securi securit$ t$.. A user !ogs into into a MOCA  MOCA  s$st s$stem em,, and and gets gets a sess sessio ion n e$ e$, that that is asso associ ciat ated ed with with a particu!ar particu!ar domain. domain. Other Other s$stems s$stems can honor honor that session session e$ Ffor remtote!$ eecuted commandsG if the$ ha(e the domain of  the origi origina! na! s$stem s$stem in their their !ist of trusted trusted domains domains.. On #I3 s$stems, the entries in this section are in the )C%IWN section of the registr$ "!e.

94

M O C A

! R O C E S S E S  



R F#I3 R F#I3 "e!d= !dap'ur!G  he %/ of the /6A& ser(er to use for authen authentic ticati ation on and authro authroXia Xiatio tion n of sing!e sing!e sign'o sign'on n app!ication users. .g. !dap=!oca!host=89dc !dap=!oca!host=89dcacme,dccom acme,dccom



6ind 4N F#I3 4N F#I3 "e!d= !dap'bind'dnG  he username to use to bind bind to the /6A& /6A& ser(er ser(er.. /ea(e /ea(e b!an b!an to bind to the /6A& ser(er anon$mous!$.



F#I3 3 "e!d= "e!d= !dap !dap'bi 'bind nd'p 'pas assw swor ordG dG  he he 6ind 6ind assw assword ord F#I password associated with the bind dn to bind to the /6A& ser(er. ser(er. /ea(e b!an to bind to the /6A& ser(er anon$mous!$. anon$mous!$.



I4 Attri*)te F#I3 Attri*)te F#I3 "e!d= !dap'uid'attrG  he name of the attribute attribute that contains contains the user>s user>s !ogin !ogin name. his is usua!!$ usua!!$ JsAMAccount#ame> for Acti(e6irector$ ser(ers and Juid> for other ser(ers.



Ro$e Attri*)te F#I3 Attri*)te F#I3 "e!d= !dap'ro!e'attrG  he name of the attribute that contains the !ist of ro!es a user is has.



Sec)re Sec)re Mode Ena*$ed Ena*$ed   F#I3 "e!d= enab!edG  nab!e the checing of securit$. his option shou!d a!wa$s be checed, or MOCA wi!! be running without an$ user authentication.



  4o%ain F#I3 4o%ain F#I3 "e!d= domainG  his is the domain that users !ogin to. to. ItLs usua!!$ usua!!$ a sing!e word word that somewhat somewhat uniBue! uniBue!$ $ identi"es the s$stem. heir session e$s are associated with that domain.



3r)sted 4o%ains 4o%ains F#I3  F#I3 "e!d= trusted'domainsG  his is a space'separated !ist of domains that we a!!ow access to from our s$stem. s$stem. his is usefu! usefu! for a!!owing a!!owing a !ogin in one s$stem s$stem to eecute eecute remot remote e commands commands on another another s$stem s$stem.. If, If, for instance, we !ogged into the


Access assword assword F#I3  F#I3 "e!d= access'passwordG ' his is the passwo password rd for the defau! defau!tt U!ogin U!ogin userU userU comman command d that that ships ships with MOCA. MOCA. In a!most a!most e(er$ case, case, the defau!t defau!t command command wi!! be o(erridden, so this "e!d is ignored.

95

M O C A



! R O C E S S E S  

F#I3 3 "e!d "e!d== encr encr$pt $ptio ionG nG  rotoco$ rotoco$ Enc&rptio Enc&rption n Metod Metod F#I his is the encr$pted protoco! used when to communication to MOCA ser(er processes.

96

M O C A

! R O C E S S E S  

&i0ense Confi=uration

he he !ice !icens nse e con" con"gu gura rati tion on page page a!!ow a!!ows s the the entr entr$ $ of !icen !icense se information information into MOCA. MOCA. A!! of these "e!ds "e!ds come come direct!$ direct!$ from the standard !icenses distributed b$ %ed&rairie Corporation. On #I3 #I3 s$s s$stems tems,, the the entri ntries es in this this sec section tion are are in the /IC#)N section section of the registr$ registr$ "!e. he corresponding corresponding "e!ds under #I3 are= 

  licensee



  productlist

97

M O C A

! R O C E S S E S  



  users



  e*pdate



(ey 

O8ner Confi=uration

98

M O C A

! R O C E S S E S  

T/e UNIB MOCA Re=istr7 he #I3 MOCA %egistr$ is a "!e made up of ?sections@, each of  whic which h cont contai ains ns one one or more more name name( (a! a!ue ue pair pairs. s. -ith ith the the eception of tass and jobs, each section corresponds to one of  the the MOCA MOCA %egi %egist str$ r$ dit ditor or>s >s tabs tabs disc discus usse sed d in the the pre( pre(io ious us section. ach ach sect sectio ion n and and name named d (a!u (a!ue e is desc descri ribe bed d abo( abo(e, e, in the the description of the -indows -indows registr$ editor. editor. Wou can refer to the description in the pre(ious section to gain a better understandi understanding ng of how the con"guration con"guration option option beha(es. beha(es. -hen there is a signi"cant dierence between the ni and -indows con"gurations, it is noted. he con"guration of tass, jobs, and connection con"gurations are s!ight!$ s!ight!$ dierent dierent.. ach tas name name de"ned de"ned b$ the ?tas'!ist@ ?tas'!ist@ usua! sua!!!$ in the prim primar ar$ $ conne nnectio ction n mana manage gerr sec section tion Fi.e Fi.e.. CO#M4%G has its own section in the registr$. registr$. )imi!ar$, )imi!ar$, each job name de"ned b$ the ?job'!ist@ usua!!$ in the primar$ connection manag manager er sect sectio ion n Fi.e Fi.e.. CO#M CO#M4% 4%GG has has its its own own sect sectio ion n in the the registr$. registr$. A!so, connection manager con"guration con"guration are de"ned b$ the ?conmgr'!ist@ in the primar$ connection manager section Fi.e. CO#M4%G ha(e ha(e there own section section in the registr$ registr$.. #O= he ?conmgr'!ist@ entr$ is not used during run'time, it is on!$ used sed for maint aintai aine nenc nce e purp purpo oses ses Fi.e Fi.e.. moca mocarregedi geditt and and mocaregimpo mocaregimportmo rtmocare caregepo geportG. rtG. he eamp!e eamp!e MOCA registr$ registr$ be!ow demonstrates this.

99

M O C A

! R O C E S S E S  

MOCA Re=istr7 9ile Se0tions and NaeF*alue !airs [!R97107] licensee=:strin5G product$list=:strin5, strin5, ...G users=:numEerG eSpdate=:yyyymmddG 3ey=:strin5G [9"1D28] port=:numEerG console$port=:numEerG initial$servers=:numEerG maS$servers=:numEerG maS$idle$servers=:numEerG maS$commands=:numEerG server$pro5ram=:strin5G password=:strin5G send$close=:6  1G server$timeout=:numEer of hoursG client$timeout=:numEer of hoursG server$command=:strin5G conm5r$list=9"1D28,:connection, connection', ...G tas3$list=:tas3 name, tas3 name', ...G XoE$list=:XoE name, XoE name', ...G [078W78] memory$file=:pathnameG mailEoS$file=:pathnameG dEliE=:liErary nameG dEuser=:strin5G dEpass=:strin5G dEconn=:strin5G dEdriver=:strin5G app$liErary=:pathnameG commands$dir=:pathnamePpathnameP ... PpathmameG [71WR8"1D71V] :nameG=:valueG . . . :nameG=:valueG [7D0] host=:hostname  ip addressG port=:numEerG hostout$dir=:pathnameG hostout$prc$dir=:pathnameG spooler$start=:6  1G spooler$sleep=:numEer of secondsGout=:numEer of secondsG

100

M O C A

! R O C E S S E S  

[079U8RV6] enaEled=:6  1G domain=:strin5G trusted$domains=:strin5 strin5 ...G access$password=:strin5G ldap$url=:strin5G ldap$Eind$dn=:strin5G ldap$Eind$password=:strin5G ldap$uid$attr=:strin5G ldap$role$attr=:strin5G [Vas3$1ame] pro5ram=:pathnameG description=:strin5G start$in=:pathnameG ar5uments=:strin5G lo5file=:pathnameG autostart=:6  1G respawn=:6  1G seTuence=:numEerG [YoE$1ame] pro5ram=:pathnameG description=:strin5G start$in=:pathnameG ar5uments=:strin5G lo5file=:pathnameG inhiEit=:6  1G schedule=:crontaE formatG [9onnection$1ame] port=:numEerG console$port=:numEerG initial$servers=:numEerG maS$servers=:numEerG maS$idle$servers=:numEerG server$pro5ram=:strin5G reload$pro5ram=:strin5G password=:strin5G send$close=:6  1G server$timeout=:numEer of hoursG client$timeout=:numEer of hoursG server$command=:strin5G

101

M O C A

! R O C E S S E S  

[9"1D28_:9onnection$1ameG] pro5ram=mocaconm5r description=:strin5G description=:strin5G start$in=:pathnameG ar5uments=$Y ZV Z0 :9onnection$1ameG lo5file=:pathnameG autostart=:6  1G respawn=:6  1G seTuence=:numEerG

102

M O C A

! R O C E S S E S  

E:aple MOCA Re=istr7 9ile [!R97107] licensee=Ccme 9orporation product$list=Cll users=%% eSpdate='%%'( 3ey=a%o3m lfawe etSo( StthE minpv te&cK [9"1D28] port=)I%% initial$servers=I maS$servers='% tas3$list=/ic38eleaseDana5er, 8eplenishmentDana5er,9"1D28_0"97V XoE$list=9lean!o5s conm5r$list=9"1D28,0"97V [0"97V] port=KI%% initial$servers=' maS$servers=% server$command=process soc3et data stream where protocol=‘0RD/!7’ [078W78] memory$file=\!70#R8HdataHcommands.mem mailEoS$file=\!70#R8HdataHmailEoS.mem commandsdir=\!70#R8HsrcHcmdsrcP\#90#R8HsrcHcmdsrcP \0!#R8HsrcHcmdsrcP\0C!#R8HsrcHcmdsrcP\D90#R8HsrcHcmdsrcP \D"9C#R8HsrcHcmdsrc dEuser=acme dEpass=production [9"1D28_0"97V] pro5ram=mocaconm5r ar5uments=$Y ZV Z0 0"97V description=9onnection Dana5er for 0imple protocol start$in=\!70#R8Hlo5 lo5file=soc3conm5r.lo5 autostart=6 [/ic38eleaseDana5er] pro5ram=pc3relm5r description=/ic3 8elease Dana5er start$in=\!70#R8Hlo5 lo5file=pc3relm5r.lo5 autostart=6 [8eplenishmentDana5er] pro5ram=replenm5r description=8eplenishment Dana5er start$in=\!70#R8Hlo5

103

M O C A

! R O C E S S E S  

lo5file=replenm5r.lo5 autostart=6 [9lean!o5s] pro5ram=perl description=9lean #aily !o5s ar5uments=\!70#R8HscriptsHcleanlo5s.pl start$in=\!70#R8Hlo5 lo5file=cleanlo5s.lo5 schedule=% % * * *

104

M O C A

! R O C E S S E S  

Startin= t/e Conne0tion Mana=er  -hen -hen starti starting ng the connec connectio tion n manage managerr, there there are a series series of  option optiona! a! argume arguments nts that can be gi(en gi(en on the command command !ine. !ine. hese hese argume arguments nts o(err o(erride ide the con"g con"gura uratio tion n speci" speci"ed ed in the MOCA registr$ and determine how the connection manager is to run.  A t$pic t$pica! a! comm command and to start start the connec connectio tion n manag manager er wou!d wou!d be= be= mocaconm5r

I.e. no options. options. his wou!d cause the connection connection manager to be started in the foreground with a!! options taen from the MOCA  registr$. A!! of the (a!id optiona! arguments are as fo!!ows FIn a!! cases, these (a!ues o(erride the defau!ts, which come from the MOCA registr$, and, b$ defau!t, do not need to be o(erriddenG= 'p ' A!!ows a port number to be speci"ed for the ser(er to connect connect to. to. his is used if the defau!t port port is a!read$ in use. 

'c Zport numberT' )peci"es the conso!e port number. he port speci"ed b$ Zport numberT becomes the conso!e port port cont contro ro!!i !!ing ng the the MOCA MOCA ser( ser(er er.. If the the cons conso! o!e e port port number is not speci"ed it is defau!ted to the ser(er port number p!us one. 

'i Zinitia! number of poo! ser(ersT ' )peci"es the initia! number of ser(ers to start upon startup of the connection manager. 

'I UCommandDCommandU  )peci"es an initia! command !ist to be eecuted on startup. 

'm Zmemor$ "!eT ' )peci"es the memor$ "!e used to !oad component commands. 

'o Zoutput "!eT ' )peci"es the "!ename for an output trace "!e. 

't Ztrace !e(e!sT !e(e!sT ')et trace !e(e!s. )ee the ?racing the the )er(er &rocess@ section be!ow for a description of trace !e(e!s. 

105

M O C A

! R O C E S S E S  



' Inhibit tass from starting.



' Inhibit jobs from starting.

') Zsec Zsecti tion onT T  )pec )pecif if$ $ the the sect sectio ion n wher where e MOCA  MOCA  connection con"guration information shou!d be !oaded. 

MOCA Console  Anothe  Anotherr uti!it uti!it$ $ that that pro(id pro(ides es he!pfu he!pfu!! inform informati ation on is the MOCA  MOCA  Conso!e. o access the conso!e, $ou simp!$ te!net to a speci"c port on the machine the MOCA Connection Manager is running on. he port to attach to is numerica!!$ one higher than the port the MOCA Connection Manager is running on.
Once $ou ha(e accessed the conso!e, $ou wi!! see the conso!e prompt. As $ou $ou "rst access the conso!e so!e,, $ou wi!! be in unpri(i!eged mode. o access pri(i!eged functions, $ou must t$pe the command UpasswordU or UpassU. )ome eamp!es of functions pro(ided are shown be!ow. D"9C 9onsoleGlist !istin5 0ervers... /R# Vime 0tarted !ast 9ommand  9onn $$$$$$$ $$$$$$$$$$$$$$$$$ $$$$$$$$$$$$$$$$$ $$$$ $$$$$ '%'K) %KH'KH&^ ^P)PI^ %KH'^H&^ %^PI(PI- '%- % '%(% %KH'KH&^ ^P-P%K %KH'^H&^ %^PI)P%% ^% % !istin5 9onnections... ;iledes 9lient Cddress /ort Vime 9onnected !ast 9ommand  /R# $$$$$$$ $$$$$$$$$$$$$$$ $$$$$$ $$$$$$$$$$$$$$$$$ $$$$$$$$$$$$$$$$$ $$$$ $$$ I &&&.K^.I'.K( %(% %KH'^H&^ %^P)'P%% %KH'^H&^ %^P)'PK (^ Rdle K &&&.K^.I'.K' 'I& %KH'KH&^ (P'P( %KH'KH&^ (P'P'( (^ Rdle D"9C 9onsoleGN CvailaEle optionsP Eye $ 9lose this console eSit $ 9lose this console filter $ V9/ ;ilterin5 commands interactive $ 9han5e Rnteractive Dode 3ill $ ill a server or connection

106

M O C A

! R O C E S S E S  

list password Tuit reload set show shutdown spawn start D"9C 9onsoleG

$ $ $ $ $ $ $ $ $

!ist various options 7nter /rivile5ed Dode 9lose this console !oad various thin5s 0et options !ist various options 0hut #own 0pawn 1ew /rocesses 0tart suEmenu

here is a!so a programmatic interface into the MOCA conso!e. he MOCA command Uconso!e commandU taes two arguments, a password, password, and command command tet to eecute. eecute. his command command can be run from msB! on an$ MOCA ser(er with the base MOCA  commands con"gured in= cPGmsTl D0Q! $ #evelopment on Vue 1ov (% IP)%PI( &&& 9opyri5ht c> 8ed/rairie 9orporation. reserved.

&&($&&&.

Cll ri5hts

Cttemptin5 connection to serverP localhost, portP )(%% as specified Ey environment ... D0Q!G console command where password = FpasswordF and command = FlistF *D0Q!G H 7Secutin5...0uccessL pid thread_id start_time last_cmd_time cmd_count state last_rcvd last_cmd last_sTl comment filedes cli_addr cli_port conn_time cli_last_cmd_time cli_cmd_count $$$ $$$$$$$$$ $$$$$$$$$$$$$$ $$$$$$$$$$$$$$ $$$$$$$$$ $$$$$$$$$$$$$$ $$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$ $$$$$ $$$$$$$$$$$$$$$$$$$$$$$$ $$$$$$$$ $$$$$$$ $$$$$$$ $$$$$$$$$ $$$$$$$$ $$$$$$$$$$$$$$ $$$$$$$$$$$$$$$$$ $$$$$$$$$$$$$ 'I- % &&&(%I(-)K &&&(%I)%I- 9"D/"171V$779 console command where password = FpasswordF and command = Flist SrefF D"9COC07Hconsole command null> null> %) '^.%.%. )I( &&&(%I)%I) &&&(%I)%I'  8ows Cffected> D0Q!G

107

M O C A

! R O C E S S E S  

Reloadin= Reloa din= Server Meor7 Meor7  After  After creat creating ing new ser(er ser(er comma commands nds or changi changing ng ser(er ser(er comm comman ands ds,, it is some someti time mes s desi desira rab! b!e e to reBu reBues estt that that the the connection manager re'!oad the memor$ segment without ha(ing to shut the connection manager down. his can be accomp!ished b$ using the MOCA Conso!e and issuing the command Ure!oad memor$U. his wi!! cause a!! of the ser(er processes to eit and re'start. re'start. )ometimes )ometimes,, a process wi!! !inger !inger for some time time after re!oading re!oading memor$ memor$.. his can be because because it has a !ong'running !ong'running Buer uer$, or becau ecause se a c!ie c!ient nt has has reBues Bueste ted d to main mainta tain in a transactio transaction n between between commands commands Fnon'auto'c Fnon'auto'commit ommit modeG, or a ser(er component has reBuested to be ept associated with a particu!ar c!ient.

S/uttin= Do8n t/e Conne0tion Mana=er  he he ser(e er(err conne nnectio ction n mana manage gerr shou shou!d !d be shut shutdo dow wn b$ accessing the MOCA Conso!e in pri(i!eged mode and issuing the command Ushutdown hardU.

Tra0in= t/e Server !ro0ess Man$ times, it is necessar$ to trace the acti(it$ of the ser(er process for a gi(en c!ient. o accomp!ish this, $ou ma$ start a ser(e ser(err proces process s b$ specif specif$ing $ing a port port to run against. against. his his port port number shou!d be dierent from the standard ports in use b$ the s$stem.
he he traci racing ng optio ptions ns are are as fo!!o o!!ows ws Fta Ftae en fro from the the he!p he!p messageG=       

M 3  A ) C %

Connection Manager
108

M O C A



! R O C E S S E S  

&

&rint process I6 in trace messages

-hen running the ser(er process in trace mode, $ou wi!! be ab!e to see the commands being eecuted b$ the c!ient app!ication. In addition, if $ou are tracing )/ commands, $ou wi!! be ab!e to see see each each indi(id indi(idua! ua! )/ statem statement ent perfo performe rmed d b$ the ser(er ser(er process. he eamp!e be!ow was captured for the 6C) command list employees= employees= ^% V$;!` &PPI' ^% V$;!` &PPI' ^% V$C82 &PPI' ^% V$08W &PPI' moddte from empmst ^% V$0Q! &PPI' moddte from empmst ^% V$0Q! &PPI) ^% V$08W &PPI) ^% V$0Q! &PPI) ^% V$0Q! &PPI) ^% V$08W &PPI) ^% V$08W &PPI) ^% V$08W &PPI) ^% V$;!` &PPI)

0erver 2ot [P%%%%%%%%'--list employees] 9allin5 #ispatch $$$$$$$$$$$$$$$$$$$$$$$$$$$$$ 7Sec [select empnum, frsnam, lstnam, empsts, where = order Ey lstnam, frsnam] ==G select empnum, frsnam, lstnam, empsts, where = order Ey lstnam, frsnam *** "8CP %> *** GGGG !oopin5... ==G commit *** "8CP %> *** 0tartin5 send 8esponse 8eturnin5  8ows 8eturnin5 from 0end 8esponse 9alled #ispatch

#otice #otice the initia initiatio tion n of the comman command d /I) /I) M&/OW M&/OW) ),, the subseBuenct trans!ation to the )/ statement Use!ect empnum, !stnam !stnam EU, the actua! actua! Orac!e Orac!e access access Fprefa Fprefaced ced b$ the ')/ ')/ indicat indicator or and inc!ud inc!uding ing the actua! actua! Orac!e Orac!e error error,, in this this case case O%A=0G, trigger eecution, and "na!!$ bui!ding of the resu!t set.

109

% U I & D I N G

A

C O M ! O N E N T  

C/apter 

$

111

C U S T O M I ( I N G

T ) E

M O C A

S E R * E R

No Database C Copon ent

%uildin= A Coponent This chapter &al(s the developer throu+h #uildin+ a component!

T/e basi0 C 0oponent he "rst tas when deciding to bui!d a new MOCA C component is to mae sure sure it "ts into the basic framewor. framewor. A C component a!wa$s taes a !ist of pointers as arguments, and a!wa$s returns a %%#H)%C %%#H)%C pointer as its its resu!ts. here is the idea of a UstupidU C component, component, which on!$ returns returns a resu!t status. status. In that case, case, it must return return a !ong (a!ue. (a!ue. Our eamp!e eamp!e wi!! be a more more traditiona! component, though, as that is much more usefu! for demonstration purposes. QereLs a samp!e C component with no database access= include :moca.hG include :mocaerr.hG include :misliE.hG include :srvliE.hG 87VU81_0V8U9V *EaseRteratelon5 *i_iterations>  int i, iterations< 87VU81_0V8U9V *ret< H* #efault the iterations to . *H iterations = i_iterations N *i_iterations P < misVrcV_;!"`, BEaseRterateP bd iterationsB, iterations><

 

H* Rnitiali4e the return struct. *H ret = srv8esultsRnite", BiB, 9"DV6/_R1V, si4eoflon5>, 1U!!>< H* /opulate the return struct. *H for i=%< i:iterations< i++> srv8esultsCddret, i><

112

% U I & D I N G

A

C O M ! O N E N T  

Database6oriented C 0opon ent.

return ret< A

his component component creates a resu!t set with count  count  rows rows in it. ach row contains the row number number. his cou!d be usefu! for emu!ating a !oop !oop for the front front end of a pipe. returned D0Q!G do loop where count = %  do somethin5 where foo = @i

he do somethin+ command somethin+ command wou!d get eecuted ten times, and the parameter foo Fassuming it taes oneG wou!d be set to the  (a!ue  (a!ue of i.

QereLs a samp!e C component with more database access= include :moca.hG

113

% U I & D I N G

A

C O M ! O N E N T  

include :stdio.hG include :strin5.hG include :stdliE.hG include include include include

:mocaerr.hG :misliE.hG :sTlliE.hG :srvliE.hG

include BintliE.hB H*  * int!o5outUser will clear the device master  *H 87VU81_0V8U9V *int!o5outUserchar *sessid>  lon5 status< char empnum[7D/1UD_!71+]< moca#ata8es *res< moca#ata8ow *row< H* #efault to no empnum. *H empnum[%] = F%F< H* #etermine the employee numEer. *H status = sTl7SecOindBselect empnum from srvre5 B Bwhere sessid = PsessidB, ?res, 1U!!, BsessidB, 9"DV6/_0V8R12, 0700R#_!71+, sessid, %, 1U!!><

 

 

if status L= e" ?? status L= e#O_1"_8"`0_C;;79V7#>  mis!o57rrorB7rror selectin5 empnumB>< A else if status == e">  row = sTl2et8owres>< misVrimcpyempnum, sTl2et0trin5res,row,Bempnum sTl2et0trin5res,row,BempnumB>, B>, 7D/1UD_!71>< A H* ;ree the result set. *H sTl;ree8esultsres>< H* 9lear out the device taEle. *H status = sTl7SecOind Bupdate devmst set lstemp = FF B Bwhere devcod = select devcod from srvre5 B B where sessid = Psessid>B, 1U!!, 1U!!, BsessidB, 9"DV6/_0V8R12, 0700R#_!71+, sessid, %, 1U!!><

114

% U I & D I N G

A

C O M ! O N E N T  

if status L= e" ?? status L= e#O_1"_8"`0_C;;79V7#>  mis!o57rrorB7rror 9learin5 !ast 7mployee on #7WD0VB>< A H* 9lear out the re5istration taEle. *H status = sTl7SecOindBdelete srvre5 where sessid = PsessidB, 1U!!, 1U!!, BsessidB, 9"DV6/_0V8R12, 0700R#_!71, sessid, %, 1U!!>< if status L= e" ?? status L= e#O_1"_8"`0_C;;79V7#>  return srv8esultsstatus, 1U!!>>< A

  A

return srv8esultse", BempnumB, 9"DV6/_0V8R12, 7D/1UD_!71, empnum, 1U!!><

he command de"nition for this command wou!d probab!$ !oo  something !ie this= 9ommandP lo5out user !evelP #90int 0tatement$QualifierP "ptional 7naEledP 6 RnsecureP 1 VypeP 9$;unction ;unctionP int!o5outUser Cr5umentP 0trin5 sessidPsession_idP reTuired 7nd$9ommand

he command returns the emp!o$ee number associated with the sess sessio ion n term termin inat ated ed,, a!th a!thou ough gh it does doesnL nLtt actu actua! a!!$ !$ need need that that information information itse!f. itse!f. his is an eamp!e eamp!e of a command choosing choosing usefu! information to return to the ca!!er, especia!!$ in the case where where the comman command d is de!eti de!eting ng the referenc reference e to that that usefu! usefu! information in the database. hat wa$, wa$, if a trigger Fsomet Fsomething hing to !og producti(it$ producti(it$ e(ents, e(ents, for instanceG instanceG was p!aced on the lo+out user  comma command, nd, it cou!d cou!d use empnum, empnum, e(en e(en thoug though h the the lo+out user  comm comman and d remo remo(e (ed d the the re!a re!ati tion onsh ship ip Fthe Fthe srvre+  srvre+  tab!eG between empnum and sessid. sessid.

115

% U I & D I N G

A

C O M ! O N E N T  

/at Ot/erinds Coponent of Options 0ustoi ations are availabl e3

C/apter 




Custoiin= t/e MOCA Server  This chapter provides descriptions o the methods and options availa#le to customi.e aspects o the MOCA server! MOCA pro(ides a series of entr$ points, or hoos, that pro(ide mechanisms for customiXation. he customiXation entr$ points are as fo!!ows= 

 Interpr  Interpreti eting ng Envir Environm onment ent Variable ariables s=

MOC MOCA per permit mits de(e de(e!o !ope pers rs to cust custom omiX iXe e en(ir n(iro onme nment  (ariab  (ariab!es !es with with this this hoo. hoo. )pecif )pecif$ $ a functi function on that that accept accepts s a sing!e char charac acte terr poin pointe terr argu argume ment nt cont contai aini ning ng the the en(ir en(iron onme ment nt string. string. Fsee sr(QooInt sr(QooInterpr erpretn( etn(ironme ironmentG. ntG. his function function is ca!!ed each time the ser(er recei(es a command stream from a c!ie c!ient nt.. At the the time time that that the the hoo hoo func functio tion n is ca!! ca!!ed ed,, the the en(ironment has a!read$ been interpreted b$ MOCA, so itLs

116

% U I & D I N G

A

C O M ! O N E N T  

safe safe to just just use use os4et s4et* *ar to "nd out out if an en(i en(iro ronm nmen entt  (ariab  (ariab!e !e has been been set. set. 

 Authent  Authentica icate te Sess Session ion=

MOCA pro(ides a mechanism for speci"c imp!ementations of  MOCA MOCA to (erif$ (erif$ the authenti authenticat cation ion of a sessio session. n. )pecif )pecif$ $ a function reBuiring no arguments. Fsee sr(QooAut sr(QooAuthent henticate) icate)essio essionG. nG. his function function is ca!!ed ca!!ed each each time the ser(er recei(es a command stream from a c!ient. he he hoo hoo must must retu return rn an inte intege gerr (a!u (a!ue e that that dete determ rmin ines es whether the current session session is UauthenticatedU. UauthenticatedU. If a session session is not not auth authen enti tica cate ted d For For auth authen enti tica cati tion on fai! fai!sG sG,, on!$ on!$ name named d commands !abe!ed as UinsecureU in the command de"nition can be eecuted. his ec!udes things !ie pass'through pass'through )/ as we!!, un!ess itLs part of a stored command. 

Updating Activity =

his mechanism pro(ides a hoo that permits the de(e!oper to trac trac !ast !ast acti(i acti(it$ t$ b$ networ networ  connec connectio tion n or sessio session n Fif  app!icab!eG. )pecif$ a function reBuiring no arguments. Fsee sr(QoopdateActi(it$G. 

olumn Descriptions=

MOCA pro(ides the abi!it$ to send !ong and short co!umn descri descripti ptions ons when when retur returning ning data data to reBues reBuestin ting g c!ient c!ients s Fin addi additi tion on to co!u co!umn mn name namesG sG.. In orde orderr to use use this this feat featur ure, e, MOCA pro(ides a hoo that accepts the number of co!umns, and three character string !ists Fchar VVG= Co!umn /ist FreadG, )hort 6escription /ist FwriteG, /ong 6escription /ist FwriteG. Fsee sr(Qoo4etCo!umn6e sr(Qoo4etCo!umn6escG. scG. 

 Error  Error !essa !essages ges=

he MOCA MOCA respo response nse pacag pacage, e, sent sent to reBue reBuesti sting ng c!ient c!ients, s, inc!udes the abi!it$ to send tetua!, !anguage speci"c, error messages. )pecif$ a function that accepts a !ongword (a!ue that represents the error number. Fsee sr(QoorrorMessageG. 

 "icense  "icense hec#in hec#ing g=

117

% U I & D I N G

A

C O M ! O N E N T  


onnection leanup=

MOCA MOCA pro( pro(id ides es a hoo hoo perm permit itti ting ng an$ an$ t$pe t$pe of c!ea c!eanu nup p functi functiona ona!it !it$ $ to be imp!eme imp!ement nt upon upon sessio session n termin terminatio ation. n. . )pecif$ a function reBuiring no arguments. Fsee sr(QooC!eanupConnectionG.

118

119

C & I E N T

A C C E S S

* I A

M M D A

C/apter 

H

121

M O C A

! & F S  &

! A C J A G E

MOCA &ibraries

MOCA

&ibraries

This chapter provides descriptions o development development unction calls used to #uild the MOCA Server processes! he he enti entire re MOCA MOCA en(i en(iro ronme nment nt is supp suppor orte ted d b$ a seri series es of  dblib$ evtlib evtlib$$ !ibr !ibrar arie ies. s. #ame #ame!$ !$,, thes these e !ibr !ibrar arie ies s are= are= srvlib, dblib$ !ibraries mcclib$ mcclib$ m%mllib$ m%mllib$ &lib$ s'llib$ s'llib$ mislib$ mislib$ oslib( hese !ibraries pro(id pro(ide e too!s too!s for e(er$t e(er$thin hing g from from e(ent e(ent hand!in hand!ing g to datet datetime ime con(ersion. he !ibraries are separated b$ t$pes of functions. It shou!d be noted that modif$ing these !ibraries is strict!$ o' !imits for an$ projects wishing to remain compatib!e with future ro!! ro!!ou outs ts of MOCA MOCA.. In gene genera ra!, !, an atte attemp mptt wi!! wi!! be made made to main mainttain ain the A&I A&I to these hese !ib !ibrar raries ies, but but the the unde underr!$in !$ing g imp! imp!em emen enta tati tion on and and "!e "!e nami naming ng con(e con(ent ntio ions ns are are subj subjec ectt to change without notice. Most users of MOCA won>t e(en ha(e that as an option, snce MOCA is not distributed in source code format. On!$ the object "!es, !ibraries and eecutab!es wi!! be distributed for a standard product re!ease. If $ou are woring from a source distribution, eep in mind that this source code is pro(ided on!$ as a read'on!$ debugging aid. #o changes shou!d be made to an$ of these "!es, !est the$ be o(erwritten during a future re!ease.

122

C & I E N T

A C C E S S

* I A

M M D A

MOCA &ibrar7 Dependen0ies srvlib

mocilib MOCAmoci.dll

oralib MOCAora.dll

ora*mllib

MOCAsrv.dll

dblib

MOCAora*mldll

m*mllib

MOCAdb.dll

ms*mllib

MOCAm*ml.dll

MOCAms*mldll

evtlib

madolib MOCAmado.dll

MOCAevt.dll

mcclib

s?llib

mislib

oslib

6lib MOCAlib.dll

A!I 9un0tions Server &ibrar7 @srv&ib

he ser(er !ibrar$ contains routines that support the acti(ities of  the ser(er manager and the ser(er process. hese routines focus on the creation, parsing, and eecution of commands. he on!$ functions that are pub!ic interfaces are as fo!!ows=

123

C & I E N T

A C C E S S

* I A

M M D A

& E G E N D

srvAddS&Results

6o$d3&pe  6o$d3&pe  indicates the function name  ItalicType   ItalicType  indicates a function parameter

6e"nition=

%%#H)%C Vsr,AddSRes)$ts sr,AddSRes)$tsFmoca6ata%es Fmoca6ata%es Vres !ong statusG statusG

6esc 6escrripti iption on==

his his func functi tion on con con(e (errts a res resu! u!tt set set into into a ret retur urn n structure. his is usefu! usefu! for a component component that wants to return the resu!ts of a )/ statement without further further manipu!ation. #ote that the res structure shou!d not not be freed after this ca!! is made.

 Argume  Arguments nts==

%eturns=

res res %esu!t %esu!t set to popu!at popu!ate e the the return return structure with. status )tatus to popu!ate the return structure with. &ointer to a return structure on success #// pointer on fai!ure.

amp!e= return srvCdd0Q!8esultsres, e"><

srvCobineMo0aDataRes

6e"nition=

!ong sr,Co%*ineMoca4ataRes Fmoca6ata%es sr,Co%*ineMoca4ataResFmoca6ata%es VVta+et, VVta+et, moca6ata%es VVsource VVsourceGG

6esc 6escrripti iption on==

his his func functi tion on is is use used d to to co combin mbine e two two resu! esu!tt set sets s into a sing!e resu!t set. his wou!d be used when repeated!$ initiating a command inside of another command when $ou desire to return a comprehensi(e resu!t set. After the ca!! to sr,Co%*ineMoca4ataRes,, tar+et wi!! sr,Co%*ineMoca4ataRes tar+et wi!! be a structure containing the combined resu!t set and source is source  is freed and set to #//.

 Argume  Arguments nts==

target target

arget arget resu!t resu!t set. set. source )ource resu!t set.

124

C & I E N T

A C C E S S

%eturns=

* I A

M M D A

eO\ on success. e#OHMMO%W e#OHMMO%W on fai!ure.

amp!e= status = srv9omEineDoca#ata8es?res, ?res'>< if status L= e">   returnstatus><

srvCobineResults

6e"nition=

!ong sr,Co%*ineRes)$ts sr,Co%*ineRes)$tsF%%#H)%C F%%#H)%C VVtar+et VVtar+et,, %%#H)%C VVsource VVsourceGG

6esc 6escrripti iption on==

his his func functi tion on is used used to comb combin ine e two two retur eturn n structures into a sing!e return structure. his wou!d be used when repeated!$ initiating a command inside of another command when $ou desire to return a comprehensi(e return structure. After the ca!! to tar+et wi!! be a structure sr,Co%*ineRes)$ts,, tar+et wi!! sr,Co%*ineRes)$ts containing the combined return structure and source is source is freed and set to #//.

 Argume  Arguments nts==

target target

arget arget return return struct structure ure.. source )ource return

structure. %eturns=

eO\ on success. e#OHMMO%W e#OHMMO%W on fai!ure.

amp!e= status = srv9omEine8esults?ret, ?ret'>< if status L= e">   returnstatus><

srvCoit

6e"nition=

!ong sr,Co%%itF(oidG sr,Co%%itF(oidG

6esc 6escrripti iption on==

his his func functi tion on is is use used d b$ b$ ser( ser(er er's 'sid ide e dae daemo mons ns to commit their transaction when the$ ha(e comp!eted a!! database changes and a!! commands ha(e "nished successfu!!$ successfu!!$.. #o component shou!d e(er ca!! this function.

%eturns=

eO\ on success. e%%O% on fai!ure.

amp!e=

125

C & I E N T

A C C E S S

* I A

M M D A

if status == e"> status = srv9ommit><

srvEnuerateAr=&ist

6e"nition=

6esc 6escrripti iption on==

 Argume  Arguments nts==

!ong sr,En)%erateAr'ist sr,En)%erateAr'istF)%*HA%4)/I) F)%*HA%4)/I) VVct* VVct*,, char Vname, name, int Voper  Voper ,  (oid  (oid VV VVdata, data, char VdtypeG dtypeG his his func functi tion on wi! wi!!! enu enume mera rate te a!! a!! the the argu argume ment nts s gi(en to the current current command. Arguments passed as de"ned arguments to the current command are not inc!uded in the enumeration. he ct* parameter ct* parameter shou!d point to a )%*HA%4/I) V (ariab!e that is initia!!$ set to #//. After each (a!id argument is found, name is name is "!!ed in with the name of the (ariab!e found, dtype has dtype has the data t$pe of the argument, data points data points to the data for the argument, and oper  is  is set to the operator that was used in the where'c!ause. he sr,reeAr'ist function sr,reeAr'ist function shou!d be ca!!ed when $ou are "nished with ct*. ct*. ct name

Argume Argument nt !ist conte contet. t. #ame of th the argumen ment found. und.   op oper Operator used on the argument in the where'c!ause, which can be one of the fo!!owing= O&%H O&%H# O&%H/ O&%H/ O&%H4 O&%H4 O&%HI)#// Fno corresponding  (a!ueG  (a!ueG O&%H#O O&%H#O# #// // Fno Fno corresponding (a (a!ueG da data 6ata fo for th the argument. dt$pe 6atat$pe of the argument, which can be one of the fo!!owing= COMW&HI# F!ong VG COMW&H/O#4 F!ong VG COMW&H)QO% COMW&H)QO% Fshort VG COMW&H+OO/A# Fshort VG COMW&HI#W Fchar VG Fsing!e b$teG COMW&H)%I#4

126

C & I E N T

A C C E S S

* I A

M M D A

Fchar VG FstringG Fdoub!e VG F(oid VVG Fmoca6ata%es VVG %eturns=

COMW&H
eO\ for each (a!id argument returned. e6+H#OH%O-)HA<<C6 e6+H#OH%O-)HA< <C6 after a!! a !! arguments ha(e been enumerated.

127

C & I E N T

A C C E S S

* I A

M M D A

srvErrorResults

6e"nition=

%%#H)%C Vsr,ErrorRes)$tsF!ong sr,ErrorRes)$tsF!ong status, status, char V mt,  mt, char Vname Vname,, char dtype, data, int loo(up...NG loo(up...NG {type} data,

6esc 6escrripti iption on==

his his func functi tion on is is use used d to to bui bui!d !d a retu return rn stru struct ctur ure e and popu!ate it with the gi(en status and defau!t error tet. he mt he mt argument  argument is a string with p!aceho!ders for data to be be substituted in. he p!aceho!der name is de!imited b$  characters. he !ooup argument determines whether or not the actua! (a!ue used to be !ooed up (ia the trans!ate message app!ication hoo.

 Argume  Arguments nts==

%eturns=

status status with.

)tatus )tatus to popu!a popu!ate te the retur return n struc structur ture e fmt 6efau!t error tet format. name &!aceho!der name. dt$pe 6atat$pe of p!aceho!der data. data &!aceho!der (a (a!ue. !ooup
amp!e= return srv7rror8esultse788"8, B9ould not open file pathnameB, BpathnameB, 9"DV6/_0V8R12, filename,   1U!!><

srvErrorResultsAdd

6e"nition=

!ong sr,ErrorRes)$tsF%%#H)%C Vret,, sr,ErrorRes)$tsF%%#H)%C Vret !ong status, status, char V mt,  mt, char Vname Vname,, char dtype, data, int loo(up...NG loo(up...NG {type} data,

6esc 6escrripti iption on==

his his func functi tion on is used used to popu popu!a !ate te an eis eisti ting ng return structure with the gi(en status and defau!t error tet. he mt he mt argument  argument is a string with p!aceho!ders for data to be substituted in. he p!aceho!der name is de!imited b$  characters. he !ooup !ooup argument determines

128

C & I E N T

A C C E S S

* I A

M M D A

whether or not the actua! (a!ue used to be !ooed up (ia the trans!ate message app!ication hoo.  Argume  Arguments nts==

%eturns=

status status with.

)tatus )tatus to popu!a popu!ate te the retur return n struc structur ture e fmt 6efau!t error tet format. name &!aceho!der name. dt$pe 6atat$pe of p!aceho!der data. data &!aceho!der (a (a!ue. !ooup
amp!e= status = srv7rror8esultsCddret, e788"8, B9ould not open file pathnameB, BpathnameB, 9"DV6/_0V8R12, filename,   1U!!><

srvE:e0uteAfterCoit> srvE:e0uteAfterRollba0

6e"nition=

(oid sr,E+ec)teAfterCo%%it sr,E+ec)teAfterCo%%itF(oid F(oid FV uncti  unction onGG F(oid Vdata G, (oid VdataG (oid F(oid FVfunctionGF(oid sr,E+ec)teAfterRo$$*ack F(oid VdataG, (oid VdataG

6escr escrip ipttion= ion=

he he sr sr( (ecut ecuteA eAft fte erCo rComm mmit itFF G and and sr(ecuteAfter%o!!bacF sr(ecuteAfter%o!!bacF G functions are used to pro(ide MOCA with a function to ca!! after it has done a commit or ro!!bac of the current transaction.  After  After a comm commit it has has succ success essfu! fu!!$ !$ comp comp!et !eted, ed, an$ functions that were registered to be eecuted  (ia a ca!! ca!! to sr(e sr(ecut cuteA eAfte fterCo rCommit mmitFF G wi!! be ca!!ed with a pointer to the data pro(ided to the ca!! to sr(ecuteAfterCommitF sr(ecuteAfterCommitF G. If the data needs to be free>d, a ca!! shou!d be made to sr(%egister6ataF G before ca!!ing

129

C & I E N T

A C C E S S

* I A

M M D A

sr(ecuteAfterCommitF sr(ecuteAfterCommitF G. It is important important to note that an$ functions registered to eecute wi!! on!$ eecute eecute if the commit succeeded. his beha(ior is dierent than the beha(ior of sr(ecuteAfter%o!!bacF sr(ecuteAfter%o!!bacF G.  After  After a ro!! ro!!bac bac  has has comp comp!et !eted, ed, an$ functi functions ons that were registered to be eecuted (ia a ca!! to sr(ecuteAfter%o!!bacF G wi!! be ca!!ed with a pointer to the data pro(ided to the ca!! to sr(ecuteAfter%o!!bacFG. sr(ecuteAfter%o!!bacFG. If the data data needs to be free>d, a ca!! shou!d be made to sr(%egister6ataF G before ca!!ing sr(ecuteAfterCommitF sr(ecuteAfterCommitF G. It is important important to note that an$ functions registered to eecute wi!! on!$ eecute regard!ess of whether or not the ro!!bac ro!!bac succeeded. succeeded. his beha(ior is dierent than the beha(ior of sr(ecuteAfterCommitF sr(ecuteAfterCommitF G.  Argume  Arguments nts==

%eturns=

data data &ointer ointer to the data data to be passed passed to the function. function. function function &ointer &ointer to the function function that shou!d be ca!!ed. (oid

amp!e= static void RncrementRntruder9ountvoid>< srv7SecuteCfter8ollEac3RncrementRntruder9ount, 1U!!><

srv9reeAr=&ist

6e"nition=

(oid sr,reeAr'istF)%*HA%4/I) sr,reeAr'istF)%*HA%4/I) =ct*G =ct*G

6esc 6escrripti iption on==

his his func functi tion on is used used to free free up memo memor$ r$ crea create ted d b$ sr,En)%erateAr'ist  ca!!s. sr,En)%erateAr'ist ca!!s.

%eturns=

(oid

amp!e= 08W_C82!R0V *ctS< char name[C821CD_!71+]< int oper< void *data< char dtype< ctS = 1U!!< while e" == srv7numerateCr5!ist?ctS, name, ?oper, ?data ?dtype> 

130

C & I E N T

A C C E S S

* I A

M M D A

H* #o somethin5 with the ar5uments. *H A srv;reeCr5!istctS><

srv9reeMeor7

6e"nition=

!ong sr,reeMe%or& Fint type, type, (oid Vpointer  Vpointer G

6esc 6escrripti iption on==

his his func functi tion on is used used to free free up memo memor$ r$ crea create ted d b$ a sr,InitiateCo%%and sr,InitiateCo%%and ca!!.  ca!!. sr,InitiateCo%%and  is t$pica!!$ used in command routines or daemon app!ications when the function wishes to perform a high !e(e! command. After performing the command, the ca!!ing modu!e is responsib!e for freeing the memor$ created b$ the command. #O= -hen using this function eterna!!$, eterna!!$, the on!$ (a!id type argument is )%*%H)%C.

 Argume  Arguments nts== %eturns=

t$pe t$pe $pe $pe of of the the poin pointer ter argume argument. nt. pointer &ointer to the data. eO\  

amp!e= srv;reeDemory08W87V_0V8U9V, 9ur/tr><

srvGetCoandSo0et

6e"nition=

)OC\H<6 Funsigned short sr,:etCo%a%ndSocketFunsigned sr,:etCo%a%ndSocket VportnoG

6esc 6escrripti iption on==

his his func functi tion on is used used to get get the the curr curren entt connection socet "!e descriptor and port number from the MOCA ser(er process when it it is using a MOCA command to hand!e the data stream Fi.e. ?ser(er'command@ is de"ned for current connection con"gurationG. his function shou!d be ca!!ed from within the MOCA  command de"ned b$ registr$ (a!ue  ?ser(er' command@. It is the responsibi!it$ responsibi!it$ of this command to process the data on the current socet "!e descriptor.

 Argume  Arguments nts==

portno portno &oint &ointer er to port port numb number er if $ou $ou wish wish to ha(e it returned.

131

C & I E N T

A C C E S S

%eturns=

* I A

M M D A

T0 If the current socet "!e descriptor is a(ai!ab!e. 0 )ocet "!e descriptor is not open. Z0 )ocet "!e descriptor is not a(ai!ab!e in this mode of MOCA ser(er process Fi.e. the ?ser(er' command@ probab!$ was not setG.

amp!e= 0"97V_;# connect;#< unsi5ned short portno< 9onnect;# = srv2et9ommand0oc3et?portno><

srvGetNeededEleent

6e"nition= 6esc 6escrripti iption on==

 Argume  Arguments nts==

%eturns=

!ong sr,:etNeededE$e%ent sr,:etNeededE$e%entFchar Fchar Vname> Vname>,, char Vname? Vname?,, char Vdtype, dtype, (oid VVdata VVdataGG his his func functi tion on is used used to grab grab data data from from the the current eecution contet. he eecution eecution contet Fwhere'c!auses and resu!ts from current and prior command eecutionsG wi!! be searched to "nd the most recent instance of a  (ariab  (ariab!e !e with with the name name cont containe ained d in either either name> or name> or name?. name?. he dt$pe and data (ariab!es (ariab!es are treated eact!$ as in sr,En)%erateAr'ist.. sr,En)%erateAr'ist name1 name1 &rimar &rimar$ $ name name to to sear search ch for. name2 )econdar$ name Fa!iasG to search for. for. Can be #//. dt$pe 6atat$pe of the argument. data 6ata for the argument. eO\ if the e!ement was found. e6+H#OH%O-)HA<<C6 e6+H#OH%O-)HA< <C6 if the argument was not found.

amp!e= char dtype< void *data< status = srv2et1eeded7lementBfooB, 1U!!, ?data, ?dtype><

srvGetServer!ort

6e"nition=

unsigned short sr,:etSer,erortFG sr,:etSer,erort FG

132

C & I E N T

A C C E S S

6esc 6escrripti iption on==

 Argume  Arguments nts== %eturns=

* I A

M M D A

his his func functi tion on is used used to get get the the port port numb number er from the MOCA ser(er process when it is not using a MOCA command to hand!e the data stream  app!ication ser(er mode Fi.e. ?ser(er' command@ is not de"ned for current connection con"gurationG. none. none. T0 &ort number of current app!ication ser(er process. Z0 &ort &ort number of app!ication ser(er is not a(ai!ab!e, probab!$ are not running from within an app!ication ser(er.

amp!e= unsi5ned short portno< portno = srv2et0erver/ort><

srv)ooAut/enti0ateSession

6e"nition= 6esc 6escrripti iption on==

 Argume  Arguments nts== %eturns=

!ong sr,8ookA)tenticateSession Fint sr,8ookA)tenticateSessionFint FV uncti  unction onGF(oidGG GF(oidGG his his func functi tion on is used used to esta estab! b!is ish h a hoo hoo to perform authentication of session information. he function accepts a pointer to a function ha(ing no arguments and returning an integer  (a!ue.  (a!ue. functi function on &ointer ointer to a func functio tion. n. eO\ on success.

srv)ooC/e0&i0ense

6e"nition=

!ong sr,8ookCeckicense Fint FV uncti  unction onGG sr,8ookCeckicenseFint F(oidGG

6esc 6escrripti iption on==

his his func functi tion on is used used to esta estab! b!is ish h a hoo hoo to perform (a!idation of !icense information. he function accepts a pointer to a function ha(ing no arguments and returning an integer (a!ue.

 Argume  Arguments nts== %eturns=

functi function on &ointer ointer to a func functio tion. n. eO\ on success.

133

C & I E N T

A C C E S S

* I A

M M D A

srv)ooCleanupConne0tion

6e"nition=

!ong sr,8ookC$ean)pConnection sr,8ookC$ean)pConnectionF(oid F(oid FV uncti  unction onGF(oidGG GF(oidGG

6esc 6escrripti iption on==

his his func functi tion on is used used to esta estab! b!is ish h a hoo hoo to perform an$ ind of c!eanup acti(it$ upon session termination. he function accepts a pointer to a function ha(ing no arguments and ha(ing a (oid return (a!ue.

 Argume  Arguments nts== %eturns=

functi function on &ointer ointer to a func functio tion. n. eO\ on success.

srv)ooErrorMessa=e

6e"nition=

!ong sr,8ookErrorMessa'e sr,8ookErrorMessa'eFchar Fchar FV uncti  unction onGG Fint numberGG

6esc 6escrripti iption on==

his his func functi tion on is used used to esta estab! b!is ish h a hoo hoo to perform error number to error tet con(ersion. he function accepts a pointer to a function accepting and integer and returning a string.

 Argume  Arguments nts== %eturns=

functi function on &ointer ointer to a func functio tion. n. eO\ on success.

srv)ooGetColunDes0

6e"nition=

!ong sr,8ook:etCo$)%n4esc sr,8ook:etCo$)%n4escF(oid F(oid FV uncti  unction onGG F!ong number, char VVco!umn/ist, char VVshort6esc/ist, char VV!ong6esc/istGG

6esc 6escrripti iption on==

his his func functi tion on is used used to esta estab! b!is ish h a hoo hoo to return short and !ong co!umn descriptions for the !ist of co!umns pro(ided. he function accepts a pointer to a function accepting an integer, integer, a co!umn !ist FcharVVG Fread on!$G, a short description !ist Fchar VVG Fwrite on!$G, and a !ong description !ist Fchar VVG Fwrite on!$G.

 Argume  Arguments nts== %eturns=

functi function on &ointer ointer to a func functio tion. n. eO\ on success.

134

C & I E N T

A C C E S S

* I A

M M D A

srv)ooInterpretEnvironent

6e"nition=

!ong sr,8ookInterpretEn,iron%ent sr,8ookInterpretEn,iron%entF(oid F(oid FV uncti  unction onGF GF char VstringGG

6esc 6escrripti iption on==

his his func functi tion on is used used to esta estab! b!is ish h a hoo hoo to perform an$ ind of processing re!ated to interpretation of en(ironment (ariab!es. he function accepts a pointer to a function accepting a string pointer and ha(ing a (oid return (a!ue.

 Argume  Arguments nts== %eturns=

functi function on &ointer ointer to a func functio tion. n. eO\ on success.

srv)oo&o=Usa=e

6e"nition=

!ong sr,8ooko'sa'e  F(oid FV uncti  unction onGFchar GFchar sr,8ooko'sa'e F(oid V(erb, char Vnoun, char Vcomponent/e(e!, !ong eecutionimeGG

6esc 6escrripti iption on==

his his func functi tion on is used used to esta estab! b!is ish h a hoo hoo to perform !ogging of component !e(e! eecution time. he function accepts a pointer to a function accepting a (erb, noun, component !e(e! and eecution time and ha(ing a (oid return (a!ue.

 Argume  Arguments nts== %eturns=

functi function on &ointer ointer to a func functio tion. n. eO\ on success.

srv)ooUpdateA0tivit7

6e"nition= 6esc 6escrripti iption on==

 Argume  Arguments nts==

!ong sr,8ookpdateActi,it& F(oid F(oid FV uncti  unction onGG F(oidGG his his func functi tion on is used used to esta estab! b!is ish h a hoo hoo to update information with regard to the session after each eecution. /ast acti(it$ time is an eamp!e of this. he function accepts a pointer to a function ha(ing no arguments and ha(ing a  (oid  (oid retu return rn (a!ue. (a!ue. functi function on &ointer ointer to a func functio tion. n.

135

C & I E N T

A C C E S S

%eturns=

* I A

M M D A

eO\ on success.

srvInitiateCoand

6e"nition=

6esc 6escrripti iption on==

 Argume  Arguments nts== %eturns=

!ong sr,InitiateCo%%and sr,InitiateCo%%andFchar Fchar Vcommand Vcommand,, %%#H)%C VVre VVrettG his his func functi tion on is used used b$ comm comman and d rou routi tine nes s or or daemon app!ications when the function wishes to perform a high !e(e! command with a c!ean eecution contet. his is one of the recommended methods for accessing commands from daemon daemon app!ications. #O=  After  After perfor performin ming g the the comm command and,, the the ca!!i ca!!ing ng modu!e is responsib!e for freeing memor$. comman command d Comman Command d to to init initiat iate. e. ret %eturn structure to popu!ate. eO\ on success.  An$ other other (a!ue (a!ue the the actua! actua! comma command nd retu returns rns..

amp!e= command = B!R0V 7D/!"6770B status = srvRnitiate9ommandcommand, ?ret>< srv;reeDemory08W87V_0V8U9V, ret>< if status L= e"> returnsrv0etup8eturnstatus, BB>><

srvInitiateCoand9orat

6e"nition=

!ong sr,InitiateCo%%andor%atF%%#H)% sr,InitiateCo%%andor%at F%%#H)% C VVret, char Vcommand, EG

6esc 6escrripti iption on==

his his func functi tion on is used used b$ comm comman and d rou routi tine nes s or or daemon app!ications when the function wishes to perform a high !e(e! command with a c!ean eecution contet using a printf'st$!e formatted command. his is one of the recommended methods for accessing commands from daemon app!ications. #O= After performing the command, the ca!!ing modu!e is responsib!e for freeing memor$.

136

C & I E N T

A C C E S S

 Argume  Arguments nts==

%eturns=

* I A

M M D A

ret ret %etur %eturn n struc structur ture e to to popu popu!at !ate. e. comma command nd
amp!e= command = B!R0V 7D/!"6770 `J787 !C0V_1CD7 = ‘bs’B status = srvRnitiate9ommand;ormat?ret, command, ;oo>< srv;reeDemory08W87V_0V8U9V, ret>< if status L= e"> returnsrv0etup8eturnstatus, BB>><

srvInitiateInline

6e"nition=

!ong sr,InitiateIn$ineFchar sr,InitiateIn$ineFchar Vcommand Vcommand,, %%#H)%C VVre VVrettG

6esc 6escrripti iption on==

his his func functi tion on is used used b$ comm comman and d rou routi tine nes s or or daemon app!ications when the function wishes to perform a high !e(e! command with the current eecution contet. his is one of the recommended methods for accessing commands from daemon daemon app!ications. app!ications. he most signi"cant dierence between  is sr,InitiateIn$ine and sr,InitiateIn$ine and sr,InitiateCo%%and sr,InitiateCo%%and is that sr,InitiateIn$ine eecutes sr,InitiateIn$ine eecutes the command in the current eecution contet. contet. herefore, arguments passed to the current command wi!! be scanned for "!!ing of arguments to downstream commands. his distinction distinction is on!$ true if the routine is being ca!!ed from another component. If ca!!ed from a daemon process, process, the two beha(e identica!!$. identica!!$. #O= After After performing the command, the ca!!ing modu!e is responsib!e for freeing memor$.

 Argume  Arguments nts== %eturns=

comman command d Comman Command d to to init initiat iate e in!in in!ine. e. ret %eturn structure to popu!ate. eO\ on success.  An$ other other (a!ue (a!ue the the actua! actua! comma command nd retu returns rns..

137

C & I E N T

A C C E S S

* I A

M M D A

amp!e= command = B!R0V 7D/!"6770B status = srvRnitiate9ommandcommand, ?ret>< srv;reeDemory08W87V_0V8U9V, ret>< if status L= e"> returnsrv0etup8eturnstatus, BB>><

srvInitiateInline9orat

6e"nition=

!ong sr,InitiateIn$ineor%at F%%#H)%C VVret, char Vcommand, 9G 9G

6esc 6escrripti iption on==

his his func functi tion on is used used b$ comm comman and d rou routi tine nes s or or daemon app!ications when the function wishes to perform a high !e(e! command with the current eecution contet using a printf'st$!e printf'st$!e formatted command. his is one of the recommended methods for accessing commands from daemon daemon app!ications. app!ications. he most signi"cant dierence between sr,InitiateIn$ineor%at  and sr,InitiateCo%%andor%at is sr,InitiateCo%%andor%at  is that sr,InitiateIn$ineor%at  eecutes the command in the current eecution contet. herefore, arguments passed to the current command wi!! be scanned for "!!ing of arguments to downstream commands. his distinction is on!$ true if the routine is being ca!!ed from another component. component. If ca!!ed from from a daemon process, the two beha(e identica!!$. identica!!$. #O= After performing the command, the ca!!ing modu!e is responsib!e for freeing memor$.

 Argume  Arguments nts==

ret ret %etur %eturn n struc structur ture e to to popu popu!at !ate. e. comma command nd
%eturns=

eO\ on success.  An$ other other (a!ue (a!ue the the actua! actua! comma command nd retu returns rns..

amp!e= command = B!R0V 7D/!"6770 `J787 !C0V_1CD7 = ‘bs’B

138

C & I E N T

A C C E S S

* I A

M M D A

status = srvRnitiateRnline;ormat?ret, command, ;oo>< srv;reeDemory08W87V_0V8U9V, ret>< if status L= e"> returnsrv0etup8eturnstatus, BB>><

srvMain

6e"nition=

!ong sr,MainFint sr,MainFint argc, char Varg(NG

6esc 6escrripti iption on==

his his fun funct ctio ion n pro( pro(id ides es the the maj major or func functi tion ona! a!it it$ $ of  a woring MOCA ser(er. ser(er. his function is deprecated, as nobod$ shou!d e(er need to de(e!op his or her own MOCA ser(er.

 Argume  Arguments nts==

argc argc arg(

Argume Argument nt count. count. Argument (ector.

amp!e= include :moca.hG include :srvliE.hG H* * D"9C 0erver *H int mainint ar5c, char **ar5v>  app_Joo3s >< H* !oad application hoo3s. *H return srvDainar5c, ar5v>< A

srvMo0aKCloseConne0tion

6e"nition=

(oid sr,Moca;C$oseConnection sr,Moca;C$oseConnectionF(oidG F(oidG

6esc 6escrripti iption on==

his his fun funct ctio ion n c!ea c!ears rs the the sta stati tic c (ari (ariab ab!e !es s used used to to eep trac of the interna! c!ient connection used for sr(MocaHecute sr(MocaHecute ca!!s. Additiona!!$, Additiona!!$, if a c!ient connection was open, then mccC!ose is used to c!ose the connection.

 Argume  Arguments nts==

#one. #one.

amp!e= include :moca.hG include :srvliE.hG H* * #aemon process *H int on_eSit>  H* normal application cleanup *H M srvDoca_9lose9onnection><

139

C & I E N T

A C C E S S

* I A

M M D A

A

srvMo0aKE:e0ute

6e"nition=

!ong sr,Moca;E+ec)teFchar sr,Moca;E+ec)teFchar Vcommand, moca6ata%es VV%esG

6esc 6escrripti iption on==

his his func functi tion on eec eecut utes es the the spe speci ci" "ed MOCA MOCA command either as a c!ient Fmccec)trG or as a ser(er Fsr(InitiateIn!ineG.

 Argume  Arguments nts==

comman command d eecute

+uer +uer conta containi ining ng comm command and to

%es Address of a pointer to a moca moca6a 6ata ta%e %es. s. Fopt FoptGG amp!e= moca#ata8es *res< moca#ata8ow *row< char Euffer[%%%]< sprintfEuffer, puElish data where world=hello>< ret_status = srvDoca_7SecuteEuffer, ?res>< M row = sTl2et8owres>< M

srvMo0aKInitConne0tion

6e"nition=

!ong sr,Moca;InitConnection Fchar Vhost, sr,Moca;InitConnectionFchar char VportG

6esc 6escrripti iption on==

his his func functi tion on init initia iate tes s a con conne nect ctio ion n to to a MOCA MOCA ser(er running on the speci"ed host and port.

 Argume  Arguments nts==

host host +uer +uer contai containin ning g hostn hostname ame to connect. port

+uer co containi ining po port nu number on on ho host.

amp!e= stat = srvDoca_Rnit9onnectionlocalhost, )I%%><

140

C & I E N T

A C C E S S

* I A

M M D A

srvRe=isterData> srvRe=isterData> srvUnre=isterData srvUnre=isterData

6e"nition=

(oid sr,Re'ister4ataF(oid sr,Re'ister4ataF(oid Vpointer  Vpointer , (oid FVdestructor  FVdestructor GF(oid GF(oid VGG (oid F(oid Vpointer  Vpointer G sr,nre'ister4ataF(oid sr,nre'ister4ata

6esc 6escrripti iption on==

he he sr sr(%eg (%egis iste ter6 r6at ata a fun funct ctio ion n is is use used d to to te! te!!! MOCA about a piece of data that needs to be freed. At the end of the transaction Fat commit or ro!!bac timeG, MOCA wi!! free the data speci"ed in pointer , using the standard C function freeF G, or a!ternati(e!$, a!ternati(e!$, the function pointed to b$ destructor . his a!!ows comp!e data structures such as !ined !ists to be freed without forcing MOCA to now an$thing about the data structure. One use for this mechanism is to pass we!! nown Fto an app!icationG, comp!e data structures around between components on a sing!e MOCA ser(er, ser(er, without ca!!ing component functions direct!$. direct!$. A component can can pub!ish a pointer to the registered data (ia the COMW&H4#%IC MOCA datat$pe, and another function can get that same piece of data passed to it (ia a 4#%IC argument t$pe. Ca!!ing sr(nregister6ata wi!! unregister the data, so that the C function freeF G or the gi(en destructor function wi!! not be ca!!ed for the gi(en data at the end of the transaction.

 Argume  Arguments nts==

%eturns=

ptr &ointer ointer to the data data to be freed. freed. destru destructo ctorr &oint &ointer er to the the functi function on that that wi!! free free the data. (oid

amp!e= static void ;ree"rder!istvoid *>< srv8e5ister#ataorder!istJead, ;ree"rder!ist><

srvReleaseJeepalive

6e"nition=

(oid sr,Re$ease
141

C & I E N T

A C C E S S

6esc 6escrripti iption on==

 Argume  Arguments nts== %eturns=

* I A

M M D A

his his func functi tion on is used used to re!e re!eas ase e a eep eepa! a!i( i(e e session that was started with sr,Re=)est
amp!e= srv8eleaseeepaliveBint2enerate!aEelB><

srvRe;uestJeepalive

6e"nition=

(oid sr,Re=)est
6esc 6escrripti iption on==

his his func functi tion on is used used to begi begin n a eep eepa! a!i( i(e e session. In genera!, MOCA components components shou!d shou!d be written to be state!ess. state!ess. hat is, the$ shou!d not assume that the process the$ run in wou!d eist at a!! after the$ "nish "nish eecuting. If a component has some important state information Fe.g. open "!es, accumu!ated data structures, etc.G and it wants to ensure that successi(e eecutions of the same For a re!atedG command wi!! run in the same process, it can use sr,Re=)est
 Argume  Arguments nts==

id Identi Identi"e "err of of the the eepa! eepa!i(e i(e sessio session. n. c!ea c!eanu nup p &ointe interr to the funct unctio ion n tha thatt wi!! wi!! c!eanup the eepa!i(e session if if ends premature!$.

%eturns=

(oid

amp!e= static lon5 saved!evel< static void 9leanupvoid>    mis0etVrace;ile1U!!><   mis0etVrace!evel;romCr5BB><

142

C & I E N T

A C C E S S

* I A

M M D A

mis0etVrace!evelsaved!evel, >< saved!evel = %< A void *int0etVracechar *filename, char *level>  if strlenlevel>>    mis0etVrace;ilefilename>< saved!evel = mis2etVrace!evel ><  

     

mis0etVrace!evel;romCr5level>< srv8eTuesteepaliveBint0etVraceB, 9leanup>< A else  mis0etVrace;ile1U!!>< mis0etVrace!evel;romCr5BB>< mis0etVrace!evelsaved!evel, >< saved!evel = %<

 

srv8eleaseeepaliveBint0etVraceB>< A returnsrv8esultse", 1U!!>><

A

srvResults

6e"nition=

%%#H)%C Vsr,Res)$tsF!ong status, sr,Res)$tsF!ong status, char Vname Vname,, char dtype, !ong len+th, len+th, {type} data, data, ...NG

6esc 6escrripti iption on==

his his func functi tion on is is use used d to to bui bui!d !d a retu return rn stru struct ctur ure e and return an error code F"rst eamp!eG or is used to create a return structure containing a sing!e row. row.

 Argume  Arguments nts==

%eturns=

status status with. dt$pe !ength data

)tatus )tatus to popu!a popu!ate te the retur return n struc structur ture e name Co!umn name. 6atat$pe of co!umn. /ength of co!umn (a!ue. Co!umn (a!ue. E Additiona! name, name, dtype, dtype, len+th and len+th and data arguments for each additiona! co!umn. &onter to a return structure on success. #// on fai!ure.

amp!e= return srv8esultsstatus, 1U!!><

143

C & I E N T

A C C E S S

* I A

M M D A

$ or Z return srv8esultse", BschtypB, 9"DV6/_9JC8, BdaycodB, 9"DV6/_9JC8, BpricodB, 9"DV6/_9JC8, BschEatB, 9"DV6/_9JC8,   1U!!><

!12#09_!71, !12#09_!71, /8R9"#_!71, 09JOCV_!71,

schtyp, daycod, pricod, schEat,

srvResultsAdd

6e"nition=

!ong sr,Res)$tsAddF%%#H)%C sr,Res)$tsAddF%%#H)%C Vret, {type} data, data, ...NG

6esc 6escrripti iption on==

his his func functi tion on is used used to add add a row row to to a res resu! u!tt set set bui!t with sr(%esu!tsInit or sr(%esu!ts. sr(%esu!ts. his a!!ows a component to easi!$ mae a mu!ti'row return structure.

 Argume  Arguments nts==

%eturns=

ret ret data

%etur %eturn n struc structur ture e to to add add the data data to. to.
amp!e= status = srv8esultsCddret, schtyp, daycod, pricod, schEat>> if status L= e">    srv;reeDemoryret>< return srv8esultsstatus, 1U!!>< A

srvResultsInit

6e"nition=

%%#H)%C Vsr,Res)$tsInitF!ong sr,Res)$tsInitF!ong status, char Vname Vname,, char dtype, !ong len+th, len+th, ...NG

6esc 6escrripti iption on==

his his func functi tion on is is use used d to to bui bui!d !d a se! se!et eton on resu resu!t !ts s structure Fone with datat$pes but no data rowsG. his can then be added to with the use of sr(%esu!tsAdd. his a!!ows a component component to easi!$ mae a mu!ti'row return structure.

 Argume  Arguments nts==

status status with. dt$pe !ength

)tatus )tatus to popu!a popu!ate te the retur return n struc structur ture e name Co!umn name. 6atat$pe of co!umn. /ength of co!umn (a!ue.

144

C & I E N T

A C C E S S

* I A

M M D A

E Additiona! name, name, dtype and dtype and len+th arguments for each additiona! co!umn. %eturns=

&onter to a return structure on success. #// on fai!ure.

amp!e= ret = srv8esultsRnite", BiB, 9"DV6/_R1V, si4eoflon5>, BnameB, 9"DV6/_9JC8, (%, BaddressB, 9"DV6/_9JC8, (%, Bmaiden_nameB, 9"DV6/_9JC8, (%,   1U!!>< for i=%< i:iterations< i++>    srv8esultsCddret, i, ib'NB"ddBPB7venB, B(%% Dain 0t.B, BOlueB>< A

srvRollba0

6e"nition=

!ong sr,Ro$$*ack F(oidG F(oidG

6esc 6escrripti iption on==

his his func functi tion on is is use used d b$ b$ ser( ser(er er's 'sid ide e dae daemo mons ns to ro!! bac their transaction when the$ ha(e encountered an error or for some other reason want to bac out of a transaction. #o component shou!d e,er  ca!!  ca!! this function.

%eturns=

eO\ on success. 6atabase error number on fai!ure.

amp!e= if status L= e"> status = srv8ollEac3><

srvSetCoandSo0et

6e"nition= 6esc 6escrripti iption on==

(oid sr,SetCo%%andSocket sr,SetCo%%andSocket F)OC\H<6  F)OC\H<6 socetHfd, unsigned short portnoG his his fun funct ctio ion n sets sets the the con conne nect ctio ion n "!e "!e desc descri ript ptor or and port number for a moca ser(er process running in command mode Fi.e. ser(er' command is de"ned for for the connectionG. #O= his function shou!d rea!!$ not be used un!ess  $our  $our crea created ted $our $our own own ser(er ser(er app!ic app!icati ation on  ?ser(er'program@ is de"nedD $ou shou!d not

145

C & I E N T

A C C E S S

* I A

M M D A

o(erride the socet MOCA ser(er is connected to. to.  Argume  Arguments nts==

socet socetHfd Hfd "!e descr descript iptor or for incomi incoming ng soc socet et connection. portno &ort number for incoming so socet connections.

%eturns=

(oid

amp!e= 0"97V_;# 9onnect;#< Unsi5ned short portno< . . . srv0et9ommand0oc3et9onnect;#, portno><

srvSetReturnStatus

6e"nition=

(oid sr,SetRet)rnStat)s sr,SetRet)rnStat)s F%%#H)%C  F%%#H)%C Vret ret, !ong statusG statusG

6esc 6escrripti iption on==

his his fun funct ctio ion n sets sets the the ret retur urn n stat status us for for a retu return rn structure.

 Argume  Arguments nts== %eturns=

ret ret stat status us

%etur %eturn n struc structur ture e to to set set the status status for for. )tat )tatus us to to set set in in the the ret retur urn n stru struct ctur ure e

(oid

amp!e= srv0et8eturn0tatusret, e#O_1"_8"`0_C;;79V7#><

srvSetServer!ort

6e"nition=

(oid sr,SetSer,erort Funsigned sr,SetSer,erort  Funsigned short portnoG

6esc 6escrripti iption on==

his his func functi tion on sets sets the the por portt num numbe berr fo for a moca moca ser(er process running in app!ication mode Fi.e. ?ser(er'command@ is not de"ned for the connectionG. #O= his function shou!d rea!!$ not be used un!ess $our created $our own ser(er app!ication  ?ser(er'program@ is de"nedD $ou shou!d not o(erride the socet s ocet MOCA ser(er is connected to.

 Argume  Arguments nts== %eturns=

portno portno &ort &ort number number for for inco incomin ming g soce socett connections. (oid

amp!e= 0"97V_;# 9onnect;#<

146

C & I E N T

A C C E S S

* I A

M M D A

& E G E N D

6o$d3&pe  6o$d3&pe  indicates the function name  ItalicType   ItalicType  indicates a function parameter Unsi5ned short portno< . . . srv0et9ommand0oc3et9onnect;#, portno><

MOCA Client Communication Library (mccLib) he MOCA MOCA C!ient C!ient Commun Communica icatio tion n /ibrar /ibrar$ $ contai contains ns routi routines nes speci" speci"ca! ca!!$ !$ design designed ed to enab!e enab!e c!ient c!ient commun communica icatio tion n with with the MOCA ser(er and the processing of data sent from the MOCA  ser(er to the c!ient app!ication. 00DisableAutoCoit

6e"nition=

!ong %cc4isa*$eA)toCo%%it %cc4isa*$eA)toCo%%itFmccC!ientInfo FmccC!ientInfo VclientG clientG

6esc 6escrripti iption on==

his his func functi tion on is used used to perm permit it comm comman ands ds to be issued in manua! commit mode. -hen auto commit is disab!ed, it sta$s disab!ed unti! it is ep!icit!$ enab!ed. Care shou!d be used when disab!ing auto commit.

 Argume  Arguments nts== %eturns=

c!ient c!ient &ointer ointer to a c!ie c!ient nt info informa rmatio tion n structure. eO\ on success. e%%O% on fai!ure.

00EnableAutoCoit

6e"nition=

!ong %ccEna*$eA)toCo%%it FmccC!ientInfo %ccEna*$eA)toCo%%itFmccC!ientInfo VclientG clientG

6esc 6escrripti iption on==

his his func functi tion on is used used to perm permit it comm comman ands ds to be issued in auto commit mode. -hen auto commit is enab!ed, it sta$s enab!ed unti! it is ep!icit!$ disab!ed. Auto commit mode is the defau!t.

147

C & I E N T

A C C E S S

 Argume  Arguments nts== %eturns=

* I A

M M D A

c!ient c!ient &ointer ointer to a c!ie c!ient nt info informa rmatio tion n structure. eO\ on success. e%%O% on fai!ure.

00E:e0Str 

6e"nition=

!ong %ccE+ecStr  FmccC!ientInfo  FmccC!ientInfo Vclient Vclient,, char Vcommand, command, moca6ata%es VVres VVresGG

6esc 6escrripti iption on==

his his func functi tion on is used used to send send a com comma mand nd to the the MOCA ser(er and recei(e a response pacage corresponding to the return (a!ues associated with the command. If res is res is sent as #//, the resu!ts are discarded upon receipt and on!$ the return code from the ca!!ed command is returned. Otherwise, the resu!ts must be freed as an$ other moca6ata%es. F)ee the )/ !ibrar$ section for more informationG

 Argume  Arguments nts==

%eturns=

c!ient c!ient &ointer ointer to a c!ie c!ient nt info informa rmatio tion n struct structure ure.. comman command d Comman Command d to eecute. res %esu!t set to popu!ate. eO\ on success.  An$ other other (a!ue (a!ue the the actua! actua! comma command nd retu returns rns..

amp!e= include :mccliE.hG if is!o55edRn>  is!o55edRn = ;C!07< sprintfcommand, Blo5out user where sessid=BbsBB,   sessid>< result = mcc7Sec0tr?client, command, 1U!!>< A

00Close

6e"nition=

!ong %ccC$oseFmccC!ientInfo %ccC$oseFmccC!ientInfo Vclient VclientGG

6esc 6escrripti iption on==

his his func functi tion on is used used to term termin inat ate e the the !in !in between the c!ient app!ication and the MOCA ser(er.

 Argume  Arguments nts==

c!ient c!ient &ointer ointer to a c!ie c!ient nt info informa rmatio tion n structure.

148

C & I E N T

A C C E S S

%eturns=

* I A

M M D A

eO\ on success. e%%O% on fai!ure.

00Init

6e"nition=

mccC!ientInfo V%ccInitFchar %ccInitFchar Vhost Vhost,, short port, port, char Venv"tr  Venv"tr G

6esc 6escrripti iption on==

his his fun funct ctio ion n is use used d to init initia ia!i !iXe Xe the the con conne nect ctio ion n between the c!ient app!ication and the MOCA ser(er.

 Argume  Arguments nts==

host host Qostn Qostname ame to connec connectt to. to. If host host is is of of the form ?host==port@, then the port number is ignored, and the host string is parsed to get the port number. number. On certain c!ients, ta!ing to certan ser(ers, a %/ starting with ?http=@ can be used, which signi"es that the web'based MOCA protoco! shou!d be used. )ee the accompan$ing documentation on the web'based ser(er interface. port &ort number to connect to. en(&tr /ist of of en en(ironment (a (ariab!e, (a (a!ue pairs.

%eturns=

eO\ on success. e%%O% on fai!ure.

amp!e= include :mccliE.hG mcc9lientRnfo *mcc9lient< . . mcc9lient = mccRnithost, port, 1U!!><

149

C & I E N T

A C C E S S

* I A

M M D A

& E G E N D

Mis0ellaneous &ibrar7 @islib

6o$d3&pe  6o$d3&pe  indicates the function name  ItalicType   ItalicType  indicates a function parameter

he misce!!aneous !ibrar$ contains a mi of routines that did not be!on e!ong g in the the othe ther !ibr !ibrar arie ies. s. his his inc inc!ude !udes s routi outine nes s to manipu!ate datestimes and app!ication message !ogging. isAs0iiTo)e:

6e"nition=

char V%isAscii3o8e+ Fchar Fchar V AsciiS  AsciiStri trin+ n+,, !ong 2um !ong 2um#er #erO4 O4yte ytes sG

6esc 6escrripti iption on==

his his func functi tion on is is use used d to to co con(er n(ertt an A)CI A)CIII str strin ing g of characters to the matching Qe representation. he 2um he 2um#er #erO4 O4yte ytes s speci"es how man$ A)CII characters to con(ert.

%eturns=

Con(erted Character )tring &ointer

amp!e= JeS0trin5 = misCsciiVoJeSBfooEarB, strlenBfooEarB>><

is%aseConv

6e"nition=

!ong %is6aseCon, Fconst Fconst char Vinum Vinum,, int i#ase, i#ase, char Vonum, int o#ase, o#ase, int si.eG si.eG

6esc 6escrripti iption on==

his his func functi tion on does does basi basic c bas base e con con(e (ers rsio ion. n. An$ An$ string passed in wi!! be interpreted as if it were one of base i#ase and i#ase and con(erted to one of base o#ase. o#ase. he on!$ unusua! thing is the wa$ it represents numbers Fas stringsG and manipu!ates them without tr$ing to represent them as integers. As a resu!t, this is s!ight!$ s!ower than integer base con(ersion, but it wors for an$ siXe iinput nput number. number. +ases higher than 10 are represented b$ an appropriate number of uppercase /atin !etters, in a!phabetica! order. Current!$, we donLt ha(e a con(ention for representing an$ base higher

150

C & I E N T

A C C E S S

* I A

M M D A

than 8: or !ower than 2 so passing a base outside that range is an error. %eturns=

eO\ on success

amp!e= if e" == misOase9onvB'&-J-!&I((&'B, (K, foo, ', si4eof foo>>  printfBfoo has bd Einary di5itsnB, strlenfoo>>< A

151

C & I E N T

A C C E S S

* I A

M M D A

isD7nC/ar0at

6e"nition=

char V%is4&nStrcatFchar %is4&nStrcatFchar VVStrin+ VVStrin+,, char Character G

6esc 6escrripti iption on==

his his func functi tion on is used used to d$na d$nami mica ca!! !!$ $ a!t a!ter er the the siXe of Strin+ and Strin+ and concatenate the (a!ue of Character  onto  onto Strin+. Strin+.

%eturns=

#// or #ew Strin+ &ointer Strin+ &ointer

amp!e= if Lmis#yn9harcat?columnlist, ‘,’>>    freecolumnlist>< returnsrv0etup8eturne1"_D7D"86, BB>>< A

isCiStr0p

6e"nition=

!ong %isCiStrnc%pFchar %isCiStrnc%pFchar VStrin+> VStrin+>,, char VStrin+?G Strin+?G

6esc 6escrripti iption on==

his his func functi tion on is used used to perf perfor orm m a case case independent string compare of two nu!! terminated string (a!ues.

%eturns=

A !ong (a!ue of of !ess than, eB eBua! to to, or or greater than 0, according as Strin+> is Strin+> is !eicographica!!$ !ess than, eBua! to, or greater than Strin+?. Strin+?. %isCiStrnc%p maes %isCiStrnc%p maes the same comparison but !oos at most Len most Len+th +th characters.  characters.

amp!e= if Lmis9i0trcmperrfl5, B6B>> printfBVhe value is yesB><

isCiStr0p> isCiStrn0p

6e"nition= 6esc 6escrripti iption on==

%eturns=

!ong %isCiStrnc%pFchar VStrin+>,, char %isCiStrnc%pFchar VStrin+> VStrin+?, Strin+?, !ong Len !ong Len+th +thGG his his func functi tion on is used used to perf perfor orm m a case case independent string compare of two string  (a!ues  (a!ues for a de" de"ned ned !ength !ength.. A !ong (a!ue of of !ess than, eB eBua! to to, or or greater than 0, according as Strin+> is Strin+> is !eicographica!!$ !ess than, eBua! to, or greater than Strin+?, Strin+?, considering Len considering Len+th +th number  number of characters. %isCiStrc%p maes %isCiStrc%p maes the same comparison but epects nu!! terminated strings.

152

C & I E N T

A C C E S S

* I A

M M D A

amp!e= if Lmis9i0trncmperrfl5, B6B, >> printfBVhe value is yesB><

153

C & I E N T

A C C E S S

* I A

M M D A

isCiStrRepla0e

6e"nition=

char V%isCiStrRep$aceF %isCiStrRep$aceF char VSearchInStrin+ VSearchInStrin+,, char VSearch@orStrin+ VSearch@orStrin+,, char V Replac  Replaceme ementS ntStri trin+ n+GG

6esc 6escrripti iption on==

his his func functi tion on is used used to sear search ch the the str strin ing g SearchInStrin+ for SearchInStrin+ for the "rst occurrence of the string Search@orStrin+. Search@orStrin+ . he comparison is case' insensiti(e. -hen found, Search@orStrin+ is Search@orStrin+  is rep!aced with the string Rep string Replac laceme ementS ntStri trin+ n+.. his function uses ma!!ocF8cG to a!!ocate memor$ for the string it returns a pointer to.

%eturns=

#// Fif Search@orStrin+ is Search@orStrin+  is not foundG or Con(erted Character )tring &ointer

amp!e= printfB8eplaced value bsB, mis9i0tr8eplaceBCO9N2JRB, BNB, B#7;B>>< produces 8eplaced value CO9#7;2JRB>

isCiStrRepla0eAll

6e"nition=

char V%isCiStrRep$aceA$$ %isCiStrRep$aceA$$FF char VSearchInStrin+ VSearchInStrin+,, char VSearch@orStrin+ VSearch@orStrin+,, char V Replac  Replaceme ementS ntStri trin+ n+GG

6esc 6escrripti iption on==

his his func functi tion on is used used to sear search ch the the str strin ing g SearchInStrin+ for SearchInStrin+ for a!! occurrences of the string Search@orStrin+. Search@orStrin+ . he comparison is case' insensiti(e. -hen found, Search@orStrin+ is Search@orStrin+  is rep!aced with the string Rep string Replac laceme ementS ntStri trin+ n+.. his function uses ma!!ocF8cG to a!!ocate memor$ for the string it returns a pointer to.

%eturns=

#// Fif Search@orStrin+ is Search@orStrin+  is not foundG or Con(erted Character )tring &ointer

amp!e= printfB8eplaced value bsB, mis0tr8eplaceBCO9N2JRB, BNB, B#7;B>>< produces 8eplaced value CO9#7;2JRB>

154

C & I E N T

A C C E S S

* I A

M M D A

& E G E N D

6o$d3&pe  6o$d3&pe  indicates the function name  ItalicType   ItalicType  indicates a function parameter

isCiStrstr 

6e"nition=

char V%isCiStrstr Fchar Fchar VStrin+> VStrin+>,, char VStrin+?G Strin+?G

6esc 6escrripti iption on==

his his func functi tion on is used used to perf perfor orm m a case case independent search for Strin+> in Strin+> in Strin+?. Strin+?.

%eturns=

A pointer into Strin+> that Strin+> that is the "rst occurrence of Strin+?. Strin+?. If Strin+? is Strin+? is not found, it returns a #// pointer.

amp!e= if Lmis9i0trstrteSt, BwhereB>> printfBwhere$clause reTuirednB><

isD7nSprintf 

6e"nition=

!ong %is4&nSprintf Fchar Fchar VV 4uer   4uer , char V @orm  @ormat, at, 9G

6esc 6escrripti iption on==

his his func functi tion on is used used to d$na d$nami mica ca!! !!$ $ bui bui!d !d a string in a sprintf'!ie sprintf'!ie fashion. he gi(en buer buer is freeF Gd Gd before being used. his function uses uses ma!!ocF8cG to a!!ocate memor$ for the gi(en buer, which the ca!!er is responsib!e for freeing.

%eturns=

he number of b$tes transmitted into the buer.  A (a!ue (a!ue !ess !ess than than 0 is is retu returne rned d if an err error or occurred.

amp!e= if mis#yn0printf?Euffer, Bbs bsB, Jello, world>>    returne788"8>< A

isD7nStr0at

6e"nition=

char V%is4&nStrcatFchar VVStrin+>,, char %is4&nStrcatFchar VVStrin+> VStrin+?G Strin+?G

155

C & I E N T

A C C E S S

* I A

M M D A

6esc 6escrripti iption on==

his his func functi tion on is used used to d$na d$nami mica ca!! !!$ $ a!t a!ter er the the siXe of Strin+> and Strin+> and concatenate the (a!ue of Strin+? onto Strin+? onto Strin+>. Strin+>. his function uses rea!!ocF8cG to rea!!ocate memor$ for the gi(en buer, which the ca!!er is responsib!e for freeing.

%eturns=

#// or #ew Strin+> &ointer Strin+> &ointer

amp!e= if Lmis#yn0trcat?columnlist, Bprtnum,B>>    freecolumnlist>< returnsrv0etup8eturne1"_D7D"86, BB>>< A

isD7nStr0p7

6e"nition=

char V%is4&nStrcp& Fchar Fchar VVStrin+> VVStrin+>,, !ong  BataLe  BataLen+t n+th hG

6esc 6escrripti iption on==

his his func functi tion on is used used to d$na d$nami mica ca!! !!$ $ a!t a!ter er the the siXe of Strin+> and Strin+> and cop$ the contents of Strin+? into Strin+>. Strin+>. he gi(en )tring1 argument is freeF Gd before being used. his function uses ma!!ocF8cG to a!!ocate memor$ for the gi(en buer, which the ca!!er is responsib!e for freeing.

%eturns=

#// or #ew Strin+> &ointer Strin+> &ointer

amp!e= if Lmis#yn0trcpy?strin5, Bnew lon5er strin5B>>    freestrin5>< returnsrv0etup8eturne1"_D7D"86, BB>>< A

isD7nStrn0at

6e"nition=

char V%is4&nStrncatFchar VVStrin+>,, %is4&nStrncatFchar VVStrin+>  char VStrin+? VStrin+?,, !ong Len !ong Len+th +thGG

6esc 6escrripti iption on==

his his func functi tion on is used used to d$na d$nami mica ca!! !!$ $ a!t a!ter er the the siXe of Strin+> and Strin+> and concatenate the (a!ue of Strin+?, Strin+?, for Len for Len+th +th characters,  characters, onto Strin+>. Strin+>. his function uses rea!!ocF8cG to rea!!ocate memor$ for the gi(en buer, buer, which the ca!!er is responsib!e for freeing.

%eturns=

#// or #ew Strin+> &ointer Strin+> &ointer

156

C & I E N T

A C C E S S

* I A

M M D A

amp!e= if Lmis#yn0trncat?columnlist, Bprtnum,B, ^>>    freecolumnlist>< returnsrv0etup8eturne1"_D7D"86, BB>>< A

157

C & I E N T

A C C E S S

* I A

M M D A

isD7nStrn0p7

6e"nition=

char V%is4&nStrncp& Fchar Fchar VVStrin+> VVStrin+>,,  !ong Bat  !ong BataLe aLen+t n+th h, !ong Len !ong Len+th +thGG

6esc 6escrripti iption on==

his his func functi tion on is used used to d$na d$nami mica ca!! !!$ $ a!t a!ter er the the siXe of Strin+> and Strin+> and cop$ the contents of Strin+?, Strin+?, for Len for Len+th +th characters,  characters, into Strin+>. Strin+>. he gi(en )tring1 argument is freeF Gd before being used. his function uses ma!!ocF8cG to a!!ocate memor$ for the gi(en buer, buer, which the ca!!er is responsib!e for freeing.

%eturns=

#// or #ew Strin+> &ointer Strin+> &ointer

amp!e= if Lmis#yn0trncpy?strin5, Bnew lon5er strin5B, strlenBnew lon5er strin5B>>>    freestrin5>< returnsrv0etup8eturne1"_D7D"86, BB>>< A

isEnd9ind9ile

6e"nition=

!ong %isEndindi$eF!ong %isEndindi$eF!ong Conte*tG Conte*tG

6escr escrip ipttion= ion=

his his func functi tio on is use used to to co comp!e mp!ete te the the Conte*t created b$ a ca!! to %isindi$e. %isindi$e. It is important to c!ose the contet with this ca!! after a!! desired ca!!s to %isindi$e are %isindi$e are made.

%eturns=

eO\  

amp!e= conteSt = %< status = mis;ind;ilefilename, ?file, ?conteSt>< if status L= e">  printfB1o matchin5 filesB><   returne1"_D"87_;R!71CD70>< A printfB;irst file is bsB, file>< freefile>< while status = mis;ind;ilefilename, ?file, ?conteSt>> == e">  printfB1eSt file is bsB, file><   freefile><

158

C & I E N T

A C C E S S

* I A

M M D A

A mis7nd;ind;ile ?conteSt><

isE:pand*ars

6e"nition= 6esc 6escrripti iption on==

%eturns=

char V%isE+pandVarsFchar %isE+pandVarsFchar Vout Vout,, char Vin Vin,, !ong si.e, si.e, char VFV unc  uncGFchar VGG his his func functi tion on is used used to epa epand nd en(i en(iro ronm nmen entt  (ariab  (ariab!es !es in a string. string. ItLs ItLs part particu icu!ar !ar!$ !$ usef usefu! u! for for reso!(ing strings stored in a con"guration "!e. he function un function unc c is used to epand the identi"ers. If un If unc c is #//, geten(FG is used. he function recogniXes both #I3 and 6O)' st$!e (ariab!e references F*A% and *A%G he output string

amp!e= mis7SpandWarspath, cf5_path, si4eof path, 1U!!><

159

C & I E N T

A C C E S S

* I A

M M D A

is9ind9ile

6e"nition=

!ong %isindi$eF %isindi$eF char V @ileSp  @ileSpeci ecifc fcati ation on,, char VV Return  Returned@ ed@ile ile2am 2ame e, !ong VConte*t VConte*tGG

6esc 6escrripti iption on==

his his func functi tion on is used used to begi begin n a !is !istt of of "!e "!ena name mes s matching @il matching @ileSp eSpeci ecifc fcatio ation n and continue processing through the !ist unti! a!! "!enames ha(e been returned. pon comp!etion, it is necessar$ to p!ace a ca!! to %isEndindi$e to %isEndindi$e to re!ease the Conte*t. Conte*t. he "!e returned must be freed upon return.

%eturns=

eO\, e#OHMO%H
amp!e= conteSt = %< status = mis;ind;ilefilename, ?file, ?conteSt>< if status L= e">  printfB1o matchin5 filesB><   returne1"_D"87_;R!71CD70>< A printfB;irst file is bsB, file>< freefile>< while status = mis;ind;ilefilename, ?file, ?conteSt>> == e">  printfB1eSt file is bsB, file><   free;ile>< A mis7nd;ind;ile?conteSt><

is9oratDate

6e"nition= 6esc 6escrripti iption on==

%eturns=

char V%isor%at4ateFchar %isor%at4ateFchar V BateSt  BateStrin rin+ +G his his func functi tion on is used used to prod produc uce e a dat date e str strin ing g based o of the input Bat input  BateSt eStrin rin+ + picture mas. -hen ca!!ed with a a Bat  BateSt eStrin rin+ + of Udd'mmm'  $$$$U,  $$$$U, this this func functio tion n wi!! wi!! retu return rn U08'Oc U08'Oct'1 t'199 997U. 7U.  *a!id  *a!id mas mas (a!ue (a!ues s are are U$$$$U, U$$$$U, U$$U, U$$U, UmmmU, UmmmU, UmmU, UdddU, and UddU. Current
amp!e= printfB9urrent date is bsB,mis;ormat#ateBmm$dd$yyB>><

160

C & I E N T

A C C E S S

* I A

M M D A

161

C & I E N T

A C C E S S

* I A

M M D A

is9oratTie

6e"nition=

char V%isor%at3i%eFchar %isor%at3i%eFchar VTimeStrin+ VTimeStrin+GG

6esc 6escrripti iption on==

his his func functi tion on is used used to prod produc uce e a tim time e str strin ing g based o the input TimeStrin+ picture TimeStrin+ picture mas. -hen ca!!ed with a TimeStrin+ of TimeStrin+ of Uhh=mmU, this function wi!! return U11=0]U. *a!id mas (a!ues are UhhU, UmmU, and UssU.

%eturns=

Current
amp!e= printfB9urrent time is bsB,mis;ormatVimeBhhPmmPssB>><

is)e:ToAs0ii

6e"nition=

char V%is8e+3oAsciiFchar %is8e+3oAsciiFchar V e*Str  e*Strin+ in+GG

6escr escrip ipttion= ion=

his his func functi tio on is is use used d to to co con(er n(ertt a e a e*St *Strin rin+ + of characters to the matching A)CII representation.

%eturns=

Con(erted Character )tring &ointer

amp!e= ascii0trin5 = misJeSVoCsciiB^'KeK(Kd^%%%KdB><

is)TT!Add)eader 

6e"nition=

!ong %is833Addeader Fchar Fchar Vname Vname,, char Vvalue, value, char ==headers56G ==headers56G

6esc 6escrripti iption on==

his his func functi tion on adds adds a hea heade derr to to the the gi(e gi(en n !is !istt of of headers. headers. he headers can headers can then be passed to misQ&&ostF G to be added to the headers in headers in the Q& reBuest. he ca!!er shou!d free headers when headers when done b$ ca!!ing misQ&
%eturns=

eO\  

is)TT!D7nEs0ape F is)TT!D7nUnes0ape

6e"nition=

char V%is8334&nEscape %is8334&nEscapeFchar Fchar Vstrin+ Vstrin+GG char V%is8334&nnescape %is8334&nnescapeFchar Fchar Vstrin+G strin+G

6esc 6escrripti iption on==

hes hese e fun funct ctio ions ns esca escape peu une nesc scap ape e the the gi(e gi(en n string for transport across an Q& connection.

162

C & I E N T

A C C E S S

* I A

M M D A

he ca!!er shou!d free the returned string when done. %eturns=

&ointer to the escapedunescaped string.

amp!e= escaped0trin5 = misJVV/#yn7scapestrin5><

is)TT!Es0ape F is)TT!Unes0ape

6e"nition=

int %is833EscapeFchar Vin, char =out, char =out, !ong %is833Escape Fchar Vin, outsi.eG outsi.eG int %is833nescape Fchar Vin, Vin, %is833nescapeFchar char =out, char =out, !ong outsi.e !ong outsi.eGG

6esc 6escrripti iption on==

hes hese e fun funct ctio ions ns esca escape peu une nesc scap ape e the the gi(e gi(en n string for transport across an Q& connection.

%eturns=

he number of characters that were escapedunescaped.

amp!e= nchars = misJVV/7scapestrin5, escaped0trin5, %%><

is)TT!9ree)eaders

6e"nition=

char V%is833:et8eaderVa$)e Fchar %is833:et8eaderVa$)eFchar ==headers56G ==headers56G

6esc 6escrripti iption on==

his his func functi tion on fre frees es memo memor$ r$ asso associ ciat ated ed with with the the gi(en !ist of headers. headers. he headers argument headers argument shou!d ha(e been popu!ated b$ a pre(ious ca!! to either misQ&AddQeaderF misQ&AddQeaderF G or misQ&4et&aramsF misQ&4et&aramsF G.

%eturns=

(oid

is)TT!9ree!aras

6e"nition=

(oid %is833reeara%s %is833reeara%sFchar Fchar =params56  =params56GG

6esc 6escrripti iption on==

his his func functi tion on fre frees es memo memor$ r$ asso associ ciat ated ed with with the the gi(en !ist of params. params. he params argument params argument shou!d ha(e been popu!ated b$ a pre(ious ca!! to misQ&4et&aramsF G.

%eturns=

(oid

is)TT!Get)eader*alue

6e"nition=

char V%is833:et8eaderVa$)e Fchar Vname Vname,, %is833:et8eaderVa$)eFchar   char ==headers56G ==headers56G

163

C & I E N T

A C C E S S

* I A

M M D A

6esc 6escrripti iption on==

his his func functi tion on get gets s the the (a!u (a!ue e ass assoc ocia iate ted d with with the the gi(en header name. name. he headers argument headers argument shou!d ha(e been popu!ated b$ a pre(ious ca!! to misQ&&ostF G.

%eturns=

&ointer to the header (a!ue. #//  Cou!d not "nd a matching header.

164

C & I E N T

A C C E S S

* I A

M M D A

is)TT!GetMessa=e%od7

6e"nition=

!ong %is833:etMessa'e6od& Fchar VVms+ VVms+GG

6esc 6escrripti iption on==

his his func functi tion on gets gets the the mes messa sage ge bod$ bod$ from from the the incoming Q& reBuest reBuest from from stdin. It is meant meant to be ca!!ed ca!!ed from within a C4I eecutab!e. he ca!!er shou!d free ms+ when ms+ when done.

%eturns=

eO\ )ome error code.

amp!e= status = misJVV/2etDessa5eOody?messa5eOody><

is)TT!Get!aras

6e"nition=

!ong %is833:etara%s %is833:etara%sFchar Fchar V=params56 V=params56GG

6esc 6escrripti iption on==

his his func functi tion on gets gets the the par param amet eter ers s fro from m the the incoming Q& reBuest reBuest from from stdin. It is meant meant to be ca!!ed from within a C4I eecutab!e to popu!ate the arra$ of parameter pointers for subseBuent ca!!s to misQ&4et&aram*a!ueF misQ&4et&aram*a!ueF G. he ca!!er shou!d free params when params when done b$ ca!!ing misQ&
%eturns=

eO\ )ome error code.

amp!e= char *value,   **params< status = misJVV/2et/arams?params>< value = misJVV/2et/aramWaluefoo, params>< misJVV/;ree/aramsparams><

is)TT!Get!ara*alue

6e"nition=

char V%is833:etara%Va$)e %is833:etara%Va$)eFchar Fchar Vname, Vname, char =params56 char =params56GG

6esc 6escrripti iption on==

his his func functi tion on get gets s the the (a!u (a!ue e ass assoc ocia iate ted d with with the the gi(en parameter parameter name. he params params argument shou!d ha(e been popu!ated b$ a pre(ious ca!! to misQ&4et&aramsF G.

165

C & I E N T

%eturns=

A C C E S S

* I A

M M D A

&ointer to the parameter (a!ue. #//  Cou!d not "nd a matching parameter.

166

C & I E N T

A C C E S S

* I A

M M D A

is)TT!!ost

6e"nition=

!ong %is833ostFchar %is833ostFchar Vurl Vurl,, char Vre1uesteadersN, re1uesteadersN, char Vre1uest4ody , !ong VresponseStatus VresponseStatus,, char VVresponseReason"hrase VVresponseReason"hrase,, char VVresponseeaders VVresponseeadersN, N, char VVressonseMessa+e4ody  VVressonseMessa+e4ody G

6esc 6escrripti iption on==

his his func functi tion on perf perfor orms ms an Q& Q& post post to the the gi(en url, url, sending, in addition to the standard Q& post headers, the gi(en re1uesteaders as re1uesteaders as we!! as the gi(en re1uest4ody . he re1uesteaders argument re1uesteaders argument shou!d ha(e been popu!ated (ia one or more ca!!s to misQ&AddQeaderF misQ&AddQeaderF G. he (a!ues for for the response headers can be determined (ia (a!!s to misQ&4etQeader*a!ueF G.

%eturns=

eO\  

is&o=Debu=

6e"nition=

(oid %iso'4e*)'Fchar  @ormat mat,, EG EG %iso'4e*)'Fchar V @or

 >arn  >arnin' in'==

6eprecated. se misrc for debugging messages.

6esc 6escrripti iption on==

his his func functi tion on is used used to !og !og deb debug ug mess messag ages es..

%eturns=


amp!e= mis!o5#eEu5B9allin5 #ispatchB><

is&o=Info

6e"nition=

(oid %iso'InfoFchar %iso'Info Fchar V @orm  @ormat at,, EG EG

6esc 6escrripti iption on==

his his func functi tion on is used used to !og !og inf infor orma mati tion ona! a! messages.

%eturns=

Con(erted Character )tring &ointer

amp!e= mis!o5RnfoB0tartup 9ompleteB><

is&o=arnin=

6e"nition=

(oid %iso'>arnin'Fchar  @ormat mat,, EG EG %iso'>arnin'Fchar V @or

167

C & I E N T

A C C E S S

* I A

M M D A

6esc 6escrripti iption on==

his his func functi tion on is used used to !og !og war warni ning ng mess messag ages es..

%eturns=

Con(erted Character )tring &ointer

amp!e= mis!o5`arnin5B"rder bs JC0 OC# /9QV6B, order1umEer><

is&o=Error 

6e"nition=

(oid %iso'Error Fchar V @orm  @ormat at,, EG EG

6esc 6escrripti iption on==

his his func functi tion on is used used to !og !og err error or mess messag ages es..

%eturns=

Con(erted Character )tring &ointer

amp!e= mis!o57rrorapp7rrorDessa5estatus>><

isMD$Data

6e"nition=

char V%isM4?4ataF(oid %isM4?4ataF(oid Vdata Vdata,, unsigned int len, len, char V#u  V#u , unsigned int si.e, si.e, int #itsG #itsG

6esc 6escrripti iption on==

his his func functi tion on prod produc uces es an M67 M67 che chec csu sum m of of the the "rst len b$tes len b$tes of data, data, returning a 12'bit checsum (a!ue, stored into the string pointed to b$ #u . he #its parameter #its parameter te!!s the function how man$ bits to stu into each b$te to encode the (a!ue. If si bits are used, the resu!ting string uses the digits 0'9, the !etters A'Y, both uppercase and !owercase, !owercase, p!us UHU and U.U. If "(e bits are used, the resu!ting string uses the digits 0'9 and the uppercase !etters A'*. If four bits are used, the resu!ting string is headecima!. he M67 checsum is a cr$ptographica!!$ secure hashing a!gorithm that can be used for generating uniBue session e$s, (a!idating !icense e$s, etc..

%eturns=

he output buer

amp!e= char c3sum[%%]< misD#I#ataptr, strlenptr>, c3sum, si4eof c3sum, I><

168

C & I E N T

A C C E S S

* I A

M M D A

isStrRepla0e

6e"nition=

6esc 6escrripti iption on==

%eturns=

char V%isStrRep$aceF %isStrRep$aceF char VSearchInStrin+ VSearchInStrin+,, char VSearch@orStrin+ VSearch@orStrin+,, char V Replac  Replaceme ementS ntStri trin+ n+GG his his func functi tion on is used used to sear search ch the the str strin ing g SearchInStrin+ for SearchInStrin+ for the "rst occurrence of the string Search@orStrin+. Search@orStrin+ . -hen found, Search@orStrin+ is Search@orStrin+  is rep!aced with the string  Replac  Replaceme ementS ntStri trin+ n+.. his function uses ma!!ocF8cG to a!!ocate memor$ for the string it returns a pointer to. #// Fif Search@orStrin+ is Search@orStrin+  is not foundG or Con(erted Character )tring &ointer

amp!e= printfB8eplaced value bsB, mis0tr8eplaceBCO9N2JRB, BNB, B#7;B>>< produces 8eplaced value CO9#7;2JRB>

isStrRepla0eAll

6e"nition=

char V%isStrRep$aceA$$F %isStrRep$aceA$$F char VSearchInStrin+ VSearchInStrin+,, char VSearch@orStrin+ VSearch@orStrin+,, char V Replac  Replaceme ementS ntStri trin+ n+GG

6esc 6escrripti iption on==

his his func functi tion on is used used to sear search ch the the str strin ing g SearchInStrin+ for SearchInStrin+ for a!! occurrences of the string Search@orStrin+. Search@orStrin+ . -hen found, Search@orStrin+ is rep!aced with the string Rep string Replace lacemen mentSt tStrin rin+ +. his function uses ma!!ocF8cG to a!!ocate memor$ for the string it returns a pointer to.

%eturns=

#// Fif Search@orStrin+ is Search@orStrin+  is not foundG or Con(erted Character )tring &ointer

amp!e= printfB8eplaced value bsB, mis0tr8eplaceCllBCO9N2JRB, BNB, B#7;B>>< produces 8eplaced value CO9#7;2JRB>

isTo&o8er> isToUpper 

6e"nition=

char V%is3oower Fchar Fchar Vstrin+ Vstrin+GG char V%is3opper  V%is3opper Fchar Fchar Vstrin+ Vstrin+GG

169

C & I E N T

A C C E S S

6esc 6escrripti iption on==

%eturns=

* I A

M M D A

Con( Con(er erts ts the the str strin ing g to to a!! a!! uppe upper' r'ca case se or a!! a!! !ower'case. Note= Note= his function modi"es the string pointed to b$ strin+. strin+.  

strin+

amp!e= misVo!owername><

isTr0

6e"nition= 6escription=

(oid %is3rcFint level, char V ormat  ormat,, ...G %is3rcFint level, )ends the string in ormat  ormat,, after printf'st$!e p rintf'st$!e substitution, to the current trace "!e, if the current trace !e(e! inc!udes level. level. his is usefu! for debugging or prob!em reso!ution. reso!ution. he level parameter corresponds corresponds to one of the fo!!owing macros, which are turned on b$ the command'  !oca !ine option in parentheses. parentheses. )ee the the !oca  )roces  )rocesses ses section of this document for more information on tracing. T_@LOD   App!ic  App!icati ation on Pow Pow F't-G F't-G T_SERFER )er(er debugging Freser(edG F't3G T_SRFAR;S )er(er Argument /isting Freser(edG F'tAG T_"LSGL &/)/ debugging Freser(edG F' t6G T_SGL )/6+ !ibrar$ debugging Freser(edG F't)G

%eturns=

nothing

amp!e= misVrcV_;!"`, B7nterin5 ;unction ;ooB><

isTri> isTriR

6e"nition=

char V%is3ri%Fchar %is3ri%Fchar VTar+etStrin+ VTar+etStrin+GG char V%is3ri%R  V%is3ri%R Fchar Fchar VTar+etStrin+ VTar+etStrin+GG

6esc 6escrripti iption on==

hes hese e fun funct ctio ions ns are are use used d to to tri trim m rig right ht hand hand,, or or trai!ing, spaces o of the string (a!ue Tar+etStrin+. Tar+etStrin+ .  Note= Note= his function modi"es the string pointed to b$ Tar+etStrin+. Tar+etStrin+.

%eturns=

rimmed Tar+etStrin+ &ointer Tar+etStrin+  &ointer

amp!e= misVrimwr3ref>

170

C & I E N T

A C C E S S

* I A

M M D A

isTri&en

6e"nition=

!ong %is3ri%enFchar %is3ri%enFchar VTar+etStrin+ VTar+etStrin+,, !ong  Ma*Len  Ma*Len+th +thGG

6escr escrip ipttion= ion=

his his func functi tio on re retur turns the the !en !engt gth h of of Tar+etStrin+ if it were trimmed. he function does not automatica!!$ trim Tar+etStrin+. Tar+etStrin+.

%eturns=

rimmed *a!ue /ength

amp!e= if Ldevcod_i  misVrim!endevcod_i, #7W9"#_!71> == %> strncpydevcod, 5etenv71W_#7W9"#>, #7W9"#_!71><

isTri&R

6e"nition= 6esc 6escrripti iption on==

%eturns=

char V%is3ri%R Fchar Fchar VTar+etStrin+ VTar+etStrin+GG his his func functi tion on is used used to trim trim rig right ht and and !ef !eft, t, or !eading and trai!ing, spaces o of the string  (a!ue  (a!ue Tar+etStrin+. Tar+etStrin+ . rimmed Tar+etStrin+ &ointer Tar+etStrin+  &ointer

amp!e= strncpyptr$Grestyp, misVrim!8cptr>, 870V6/_!71><

isTriStrn0p

6e"nition=

!ong %is3ri%Strnc%pFchar %is3ri%Strnc%pFchar Vs> Vs>,, char Vs? Vs?,, !ong lenG lenG

6esc 6escrripti iption on==

his his func functi tion on is used used to perf perfor orm m a stri string ng comparison of two string (a!ues for a de"ned !ength, ignoring trai!ing spaces in both strings.

%eturns=

A !ong (a!ue of of !ess than, eB eBua! to to, or or greater than 0, according as s> is s> is !eicographica!!$ !ess than, eBua! to, or greater than s?, s?, considering len number len number of characters.

amp!e= if LmisVrim0trncmpptr$Grestyp, cptr, 870V6/_!71>>  H* #o somethin5. *H A

isTri0p7> isTrin0p7> isTri&R0p7

6e"nition=

char V%is3ri%ncp& Fchar Fchar Vout Vout,, char Vin, Vin, !ong len, len, !ong si.eG si.eG char V%is3ri%cp&  V%is3ri%cp& Fchar Fchar Vout Vout,, char Vin Vin,, !ong

171

C & I E N T

A C C E S S

* I A

M M D A

lenG lenG char V%is3ri%Rcp& Fchar Fchar Vout Vout,, char Vin Vin,, !ong lenG lenG 6esc 6escrripti iption on==

his his func functi tion on is is use used d to to co cop$ the the stri string ng poin pointe ted d to b$ in, in, and trim the output string Fout F outGG at the same time. he %is3ri%cp&  form  form assumes that the output string is at !east lenS1 lenS1 b$tes !ong. he misrim/%cp$ form trims both the !eft and right sides of the string.

%eturns=

rimmed out &ointer out &ointer

amp!e= misVrimncpyempnum, sTl2et0trin5res,row,BempnumB>, 7D/1UD_!71, si4eof empnum><

172

C & I E N T

A C C E S S

* I A

M M D A

& E G E N D

6o$d3&pe  6o$d3&pe  indicates the function name  ItalicType   ItalicType  indicates a function parameter

is*alidateDatetie9orat

6e"nition=

!ong %isVa$idate4ateti%eor%at %isVa$idate4ateti%eor%atFchar Fchar VfmtG

6esc 6escrripti iption on==

his his func functi tion on is used used to (a!i (a!ida date te the the gi( gi(en en database datetime format. format. his format format wou!d usua!!$ be used in a toHcharF G ca!! within a )/ statement.

%eturns=

eO\ he number of in(a!id characters in the gi(en format.

amp!e= Walid = misWalidate#atetime;ormatmmHddHyyyy><

D% &ibrar7 @db&ib he MOCA 6+ !ibrar$ pro(ides an )/ interface for app!ication programs. his interface is preferab!e o(er using mbedded )/ for a coup!e of reasons.
6e"nition=

!ong d*Co%%itF(oidG d*Co%%itF(oidG

173

C & I E N T

A C C E S S

6esc 6escrripti iption on==

%eturns=

* I A

M M D A

his his func functi tion on is used used to comm commit it one one or or a seri series es of )/ commands issued using d*E+ecStr . -hen issuing commands at an )/ !ibrar$ !e(e!, the de(e!oper is responsib!e for committing or ro!!ing bac the transactions. #ote= his function is a!so a(ai!ab!e as sB!Commit. eO\   e#OHMMO%W   An$ 6ataba 6atabase se 4enera 4enerated ted rror rror *a!ue Fas a negati(e numberG

amp!e= status = dE9ommit><

dbE:e0%ind

6e"nition=

!ong d*E+ec6indFchar d*E+ec6indFchar VS1lCommand VS1lCommand,, moca6ata%es VV Result  ResultSet Set,, moca+ind/ist V In4ind  In4indLis Listt, char Vname Vname,, char dtype, dtype, !ong si.e, si.e, data, int nullind...NG nullind...NG {type} data,

6esc 6escrripti iption on==

his his fun funct ctio ion n is sim simi! i!ar ar to to db dbec ec)t )trr, but but mae maes s use of bind (ariab!es. (ariab!es. he In4 he In4ind indLis Listt parameter to this function is used to pre'de"ne a bind !ist using s=$6)i$d6indistFG. s=$6)i$d6indistFG. If In+ind/ist is passed as #//, then the remaining arguments are used to de"ne de"ne a bind !ist. he +ind'speci"c +ind'speci"c datat$pes to use are COM!@#ONB?  for !ong integers to be returned from )/, COM!@9#OA?  for doub!e'precision Poating point (a!ues to be returned from )/, and COM!@CJA?? , for string (a!ues being returned from from )/.
%eturns=

eO\   e#OHMMO%W  e)/HOOH/O#4  An$ databa database' se'gen gener erate ated d erro errorr (a!ue (a!ue Fas a negati(e numberG

amp!e=

174

C & I E N T

A C C E S S

* I A

M M D A

status = dE7SecOindBselect * from rplwr3  where schEat = PschEatB, ?res, 1U!!, BschEatB, 9"DV6/_0V8R12, 09JOCV_!71, schEat, %, 1U!!>< if status == e">  for row = sTl2et8owres>< row< row = sTl2et1eSt8owrow>>  sprintftmp_Euf, BVhe Eatch is bs and the  reference is bsB, sTl2et0trin5res, row, BschEatB>, sTl2et0trin5res, row, BrplrefB>>< A A sTl;ree8esultsres>< $or$ status = dE7SecOindBdelete from pc3wr3  where schEat = PschEat B, 1U!!, 1U!!, BschEatB, 9"DV6/_0V8R12, 09JOCV_!71, schEat, %, 1U!!>< $or$ status = dE7SecOindBO72R1  Pstatus = spCllocatePin!odnum,  Pout!ocation>< 71#, ?sp0tatus, %, Bin!odnumB, 9"DV6/_0V8R12, !"#1UD_!71, lodnum, %, Bout0tolocB, 9"DV6/_9JC8/V8, si4eofstoloc>, stoloc, %, 1U!!>< $or$ mocaOind!ist *Eindlist< Eindlist = 1U!!< sTlOuildOind!ist?Eindlist, BstatusB, 9"DV6/_!"12/V8, si4eoflon5>, ?sp0tatus, %, Bin!odnumB, 9"DV6/_0V8R12, !"#1UD_!71, lodnum, %,   1U!!>< sTlOuildOind!ist?Eindlist, Bout0tolocB, 9"DV6/_9JC8/V8, si4eofstoloc>, stoloc, %, 1U!!>< status = sTl7SecOindBO7 O72R1  Pstatus = spCllocatePin!odnum,  Pout!ocation>< 71#<

175

C & I E N T

A C C E S S

* I A

M M D A

dbE:e0Str 

6e"nition=

!ong d*E+ecStr Fchar Fchar Vs1l Vs1l,, moca6ata%es VVres VVresGG

6esc 6escrripti iption on==

his his func functi tion on is used used to issu issue e )/ )/ comm comman ands ds to the database. It shou!d be noted that when $ou perform updates and de!etes through )/ !ibrar$ ca!!s, $ou are responsib!e for committing or ro!!ing bac $our transactions. In addition, whene(er $ou mae a ca!! ca! ! to dbec)tr, dbec)tr, $ou are responsib!e for free the memor$ created b$ the ca!!. If $ou do not wish to create a resu!t set, !ie when performing updates or de!etes, send #// in as the second parameter to dbec)tr. #ote= his function is a!so a(ai!ab!e as sB!ec)trFG.

 Argume  Arguments nts== %eturns=

res res sB!

%eturn %eturn struct structure ure to popu!at popu!ate. e. )/ to eecute.

eO\   e#OHMMO%W  e)/HOOH/O#4  An$ 6ataba 6atabase se 4enera 4enerated ted rror rror *a!ue Fas a negati(e numberG

amp!e= sprintfsTl, Bselect * from rplwr3  where schEat = FbsF B, schEat><  status = dE7Sec0trsTl, ?res>< if status == e">  for row = sTl2et8owres>< row< row = sTl2et1eSt8owrow>>  sprintfEuffer, BVhe Eatch is bs and the  reference is bs.B, char *> sTl2etWalueres, row, BschEatB>, char *> sTl2etWalueres, row, BrplrefB>>< A A sTl;ree8esultsres>< $or$ sprintfsTl, Bdelete from pc3wr3  where schEat = FbsF B, schEat>< status = dE7Sec0trsTl, 1U!!><

176

C & I E N T

A C C E S S

* I A

M M D A

dbE:e0Str9orat

6e"nition=

!ong d*E+ecStror%atFmoca6ata%es d*E+ecStror%at Fmoca6ata%es VVres, char Vs1l Vs1l,, EG EG

6esc 6escrripti iption on==

his his func functi tion on is used used to issu issue e )/ )/ comm comman ands ds to the database. It shou!d be noted that when $ou perform updates and de!etes through )/ !ibrar$ ca!!s, $ou are responsib!e for committing or ro!!ing bac $our transactions. In addition, whene(er $ou mae a ca!! ca! ! to dbec)tr
 Argume  Arguments nts==

res res %eturn %eturn struct structure ure to popu!at popu!ate. e. sB!
%eturns=

eO\   e#OHMMO%W  e)/HOOH/O#4  An$ 6ataba 6atabase se 4enera 4enerated ted rror rror *a!ue Fas a negati(e numberG

amp!e= status = dE7Sec0tr;ormat?res, Bselect * from rplwr3  where schEat = FbsF B,   schEat>< if status == e">  for row = sTl2et8owres>< row< row = sTl2et1eSt8owrow>>  sprintfEuffer, BVhe Eatch is bs and the  reference is bs.B, char *> sTl2etWalueres, row, BschEatB>, char *> sTl2etWalueres, row, BrplrefB>>< A A sTl;ree8esultsres><

177

C & I E N T

A C C E S S

* I A

M M D A

dbRollba0

6e"nition=

!ong d*Ro$$*ack F(oidG F(oidG

6esc 6escrripti iption on==

his his func functi tion on is is use used d to to ro! ro!!b !bac ac  one one or a ser serie ies s of )/ commands issued using d*E+ecStr . A!! commands issued since the !ast commit or ro!!bac wi!! be ro!!ed bac. -hen issuing commands at an )/ !ibrar$ !e(e!, the de(e!oper is responsib!e for committing or ro!!ing bac the transactions. #ote= his function is a!so a(ai!ab!e as sB!%o!!bacFG.

%eturns=

eO\   e#OHMMO%W   An$ 6ataba 6atabase se 4enera 4enerated ted rror rror *a!ue Fas a negati(e numberG

amp!e= dE8ollEac3 ><

dbSetSavepoint

6e"nition=

!ong d*SetSa,epointFchar d*SetSa,epointFchar Vsavepoint VsavepointGG

6esc 6escrripti iption on==

his his func functi tion on is used used to set set a sa(e sa(epo poin intt for for future ro!!bac. ro!!bac. An$ wor done between between the setting of the sa(epoint and an$ future ca!! to db%o!!baco)a(epoint db%o!!baco)a(epoint wi!! be undone, but the rest of thetransaction wi!! be continued.

%eturns=

eO\   e#OHMMO%W   An$ databa database se gener generate ated d err error or (a!ue (a!ue Fas a negati(e numberG

amp!e= dE0et0avepointallocate_test><

dbRollba0ToSavepoint

6e"nition=

!ong d*Ro$$*ack3oSa,epoint Fchar Vsavepoint VsavepointGG d*Ro$$*ack3oSa,epointFchar

6esc 6escrripti iption on==

his his func functi tion on is is use used d to to ro! ro!!b !bac ac  upda update tes s to to the the current transaction to a point speci"ed b$ the named savepoint. savepoint. An$ wor done between between the the setting of the sa(epoint and the ca!! to

178

C & I E N T

A C C E S S

* I A

M M D A

db%o!!baco)a(epoint db%o!!baco)a(epoint wi!! be undone, but the rest of thetransaction wi!! be continued. %eturns=

eO\   e#OHMMO%W   An$ 6ataba 6atabase se 4enera 4enerated ted rror rror *a!ue Fas a negati(e numberG

amp!e= dE8ollEac3Vo0avepointallocate_test><

dbGetNe:t*al

6e"nition=

char Vd*:etNe+tVa$Fchar d*:etNe+tVa$Fchar Vse1uence Vse1uenceGG

6esc 6escrripti iption on==

his his func functi tion on is used used to get get the the net net (a!u (a!ue e of of the the named seBuence.

%eturns=

A pointer to to a st static memor$ ar are that contains the net (a!ue of the seBuence named in the argument. If the seBuence doesn>t doesn>t eist, or some other error occurs, an empt$ Fnot nu!!G string is returned.

amp!e= strncpylodnum, dE2et1eStWallodnum>, !"#1UD_!71><

dbConne0t

6e"nition=

!ong d*ConnectFchar d*ConnectFchar Vuser  Vuser , char Vpass&ord Vpass&ord,, char Vconnection VconnectionGG

6esc 6escrripti iption on==

his his func functi tion on is used used to !og !og in in to to the the data databa base se that MOCA uses for the basis of its transactions. o !og in to the defau!t database connection, pass #// pointers to this function, or don>t ca!! it at a!!, since a!! the db !ibrar$ ca!!s wi!! connect to the defau!t database.

%eturns=

eO\   e#OHMMO%W   An$ 6ataba 6atabase se 4enera 4enerated ted rror rror *a!ue Fas a negati(e numberG

amp!e= dE9onnectoverUser, over/ass, over9onn><

dbClose

6e"nition=

!ong d*C$oseF(oidG d*C$oseF(oidG

179

C & I E N T

A C C E S S

* I A

M M D A

6esc 6escrripti iption on==

his his func functi tion on c!os c!oses es the the cur currrent ent dat datab abas ase e connection. In genera!, this is unneccessar$, unneccessar$, since the database connection is c!osed b$ defau!t when the process eits. eits. One of the on!$  (a!id  (a!id use uses s for for this this ca!! ca!! is to discon disconnec nectt fro from m the the database in order to re'connect with a dierent user.

%eturns=

eO\   e#OHMMO%W   An$ 6ataba 6atabase se 4enera 4enerated ted rror rror *a!ue Fas a negati(e numberG

amp!e= dE9lose ><

S& &ibrar7 @s;l&ib he functions of the )/ !ibrar$ are used to manipu!ate the moca6ata%e moca6ata%es s and moca6ata%ow moca6ata%ow structur structures. es. hese structur structures es are used to carr$ the resu!ts from 6+ !ibrar$ ca!!s, as we!! as MCC MCC !ibr !ibrar ar$ $ ca!! ca!!s. s. he he fo!! fo!!ow owin ing g func functio tions ns de"n de"ne e the the pub! pub!ic ic interfaces to )/ !ibrar$= )omething to tae note of= d*E+ecStr  popu!ates  popu!ates a moca6ata%es stru struct ctur ure. e. hou hough gh it is poss possib ib!e !e to tra( tra(er erse se this this stru struct ctur ure e manua! manua!!$ !$ b$ !ooin !ooing g a 'Tnet 'Tnet pointe pointers, rs, etc., etc., access access functi functions ons which hide the actua! structure of the functions shou!d a!wa$s be used. he access functions wi!! a!wa$s be supported, whi!e the structures ma$ change. Code written using the access functions wi!! a!wa$s wor, whereas code written which depends on the data structures ma$ brea due to some future change in the access function. s;l9reeResults

6e"nition= 6esc 6escrripti iption on==

(oid s=$reeRes)$tsFmoca6ata%es s=$reeRes)$tsFmoca6ata%es V Result  ResultSet SetGG his his func functi tion on fre frees es the the mem memor or$ $ asso associ ciat ate e wit with h an$ resu!t set created b$ d*E+ecStr . -hene(er  $ou mae mae a ca!! ca!! to d*E+ecStr , $ou are responsib!e to free the memor$ created b$ the ca!!. If $ou do not wish to create a resu!t set, !ie when performing updates or de!etes, send #// in as the second parameter to d*E+ecStr .

180

C & I E N T

A C C E S S

%eturns=

* I A

M M D A

#one

amp!e= sTl;ree8esultsres><

s;lGet%inar7Data

6e"nition=

(oid @s=$:et6inar&4ata Fmoca6ata%es @s=$:et6inar&4ataFmoca6ata%es V Result  ResultSet Set,, moca6ata%ow V Ro&"  Ro&"ointer  ointer , char VColumn2ame VColumn2ameGG

6escr escrip ipttion= ion=

his his func functi tio on can can be used sed to to pr pro(id (ide a con(enient ca!!ing interface to accessing binar$ data co!umns returned in an$ resu!t set. A pointer to the binar$ data in the co!umn wi!! be returned. If the co!umn is not COMW&H+I#A%W, a #// wi!! be returned.

%eturns=

A pointer to the binar$ data.

amp!e= data = sTl2etOinary#atares, row, BfileB><

s;lGet%inar7Data&en

6e"nition=

!ong s=$:et6inar&4ataen s=$:et6inar&4ataenFmoca6ata%es Fmoca6ata%es V Result  ResultSet Set,, moca6ata%ow V Ro&"  Ro&"ointer  ointer , char VColumn2ame VColumn2ameGG

6escr escrip ipttion= ion=

his his func functi tio on can can be used sed to to pr pro(id (ide a con(enient ca!!ing interface to accessing binar$ data co!umns returned in an$ resu!t set. he !ength of the binar$ data in the co!umn wi!! be returned. If the co!umn is not COMW&H+I#A%W, '1 wi!! be returned.

%eturns=

A !ong (a!ue representing the !ength of the binar$ data.

amp!e= len5th = sTl2etOinary#ata!enres, row, BfileB><

s;lGetDataT7pe

6e"nition=

char s=$:et4ata3&peFmoca6ata%es s=$:et4ata3&peFmoca6ata%es V Result  ResultSet Set,, char VColumn2ame VColumn2ameGG

181

C & I E N T

A C C E S S

* I A

M M D A

6esc 6escrripti iption on==

his his func functi tion on can can be used used to retu return rn what what datat$pe a certain co!umn of a resu!t set is.

%eturns=

COMW&HI# COMW&H
amp!e= switch sTl2et#ataVyperes, BprtnumB>>  case 9"DV6/_R1VP H* deal with column as inte5er *H   Erea3< case 9"DV6/_0V8R12P H* deal with column as strin5 *H   Erea3< A

s;lGet9loat

6e"nition=

doub!e s=$:et$oatFmoca6ata%es s=$:et$oatFmoca6ata%es V Result  ResultSet Set,, moca6ata%ow V Ro&"  Ro&"ointer  ointer , char VColumn2ame VColumn2ameGG

6escr escrip ipttion= ion=

his his func functi tio on can can be used sed to to pr pro(id (ide a con(enient ca!!ing interface to accessing data co!umns returned returned in an$ resu!t set. he co!umn in Buestion wi!! be con(erted to a doub!e Fwith an$ potentia! !oss of data associated with that con(ersionG, if the datat$pe is not a!read$ COMW&H
%eturns=

A doub!e precision Poating point (a!ue Fdoub!eG representing the (a!ue of the co!umn.

amp!e= maSTvl = sTl2et0trin5res, row, BmaSTvlB><

s;lGet&on=

6e"nition=

!ong s=$:eton'Fmoca6ata%es  ResultSet Set,, s=$:eton'Fmoca6ata%es V Result moca6ata%ow V Ro&"  Ro&"ointer  ointer , char VColumn2ame VColumn2ameGG

6escr escrip ipttion= ion=

his his func functi tio on can can be used sed to to pr pro(id (ide a con(enient ca!!ing interface to accessing data co!umns returned returned in an$ resu!t set. he co!umn in Buestion wi!! be con(erted to a !ong Fwith an$ potentia! !oss of data associated with that con(ersionG, if the datat$pe is not a!read$ COMW&H/O#4.

182

C & I E N T

A C C E S S

%eturns=

* I A

M M D A

A !ong (a!ue representing the (a!ue of the co!umn.

amp!e= ordTty = sTl2et0trin5res, row, BordTtyB><

s;lGetNe:tRo8

6e"nition=

moca6ata%ow Vs=$:etNe+tRow Fmoca6ata%ow Fmoca6ata%ow V Ro&"  Ro&"oin ointer  ter G

6esc 6escrripti iption on==

his his func functi tion on is used used to poin pointt to to the the net net row row of of an$ resu!ts set. It is t$pica!!$ used in conjunction with s=$:etRow  in  in a for, do, or whi!e !oop. -hen no more rows eist, the routine returns a #// pointer.

%eturns=

%ow &ointer #//

amp!e= for row = sTl2et8owres>< row<  row = sTl2et1eSt8owcur_row>>  sprintfEuffer, BVhe Eatch is bs and the  reference is bsB, char *> sTl2etWalueres, row, BschEatB>, char *> sTl2etWalueres, row, BrplrefB>>< A $or$ row = sTl2et8owres>< do  sprintfEuffer, BVhe Eatch is bs and the  reference is bsB, char *>sTl2etWalueres, row, BschEatB>, char *> sTl2etWalueres, row, BrplrefB>>< A while row = sTl2et1eSt8owrow>> L= 1U!!>< or row = sTl2et8owres>< while row>  sprintfEuffer, BVhe Eatch is bs and the  reference is bsB, char *> sTl2etWalueres, row, BschEatB>, char *> sTl2etWalueres, row, BrplrefB>>< row = sTl2et1eSt8owrow>< A

183

C & I E N T

A C C E S S

* I A

M M D A

s;lGet!revRo8

6e"nition=

moca6ata%ow Vs=$:etre,Row Fmoca6ata%ow Fmoca6ata%ow V Ro&"  Ro&"oin ointer  ter G

6esc 6escrripti iption on==

his his func functi tion on is used used to poin pointt to to the the pre( pre(io ious us row of an$ resu!ts set. set. If the gi(en row is the "rst row in the resu!t set, the routine returns a #// pointer.

%eturns=

%ow &ointer #//

s;lGetRo8

6e"nition=

moca6ata%ow Vs=$:etRow Fmoca6ata%es Fmoca6ata%es V Result  ResultSet SetGG

6esc 6escrripti iption on==

his his func functi tion on is used used to poin pointt to to the the "rst "rst row row of of an$ resu!t set. It returns a row pointer or #// pointer if the resu!t set contains no rows.

%eturns=

%ow &ointer #//

amp!e= row = sTl2et8owres><

s;lGetStrin=

6e"nition=

char Vs=$:etStrin'Fmoca6ata%es s=$:etStrin'Fmoca6ata%es V Result  ResultSet Set,, moca6ata%ow V Ro&"  Ro&"ointer  ointer , char VColumn2ame VColumn2ameGG

6escr escrip ipttion= ion=

his his func functi tio on can can be used sed to to pr pro(id (ide a con(enient ca!!ing interface to accessing data co!umns returned returned in an$ resu!t set. he co!umn in Buestion must be of t$pe COMW&HCQA%, or a nu!! pointer wi!! be returned.

%eturns=

A (a!id pointer to the data associated with a particu!ar row and co!umn of a resu!t set. set. If the co!umn in Buestion is not of t$pe COMW&HCQA%, or the data e!ement reBuested has a #// (a!ue, then a #// pointer is returned.

amp!e= misVrimncpyordnum, sTl2et0trin5res, row, BordnumB>, "8#1UD_!71, si4eof ordnum>><

184

C & I E N T

A C C E S S

* I A

M M D A

s;lGet*alue

6e"nition=

(oid Vs=$:etVa$)eFmoca6ata%es s=$:etVa$)eFmoca6ata%es V Result  ResultSet Set,, moca6ata%ow V Ro&"  Ro&"ointer  ointer , char VColumn2ame VColumn2ameGG

 >arn  >arnin' in'==

his function is deprecated. #ew code shou!d use s=$:et$oat s=$:et$oats=$:eton' s=$:eton's=$:etStrin'. s=$:etStrin'.

6escr escrip ipttion= ion=

his his func functi tio on can can be used sed to to pr pro(id (ide a con(enient ca!!ing interface to accessing data co!umns returned in an$ resu!t set. hese data co!umns can be accessed b$ position starting at Xero, as in the "rst eamp!e, or b$ co!umn name, as in the second eamp!e. Casting, in both cases, is recommended.

%eturns=

(oid pointer

amp!e= sprintfsTl, Bselect schEat, rplref from rplwr3 B Bwhere schEat = FbsF B, schEat>< status = dE7Sec0trsTl, ?res>< for row = sTl2et8owres>< row<  row = sTl2et1eSt8owrow>>  sprintfEuffer, BVhe Eatch is bs and the  reference is bsB, char *>sTl2etWalueres, row, BschEatB>, char *>sTl2etWalueres, row, BrplrefB>>< A sTl;ree8esultsres><

s;lIsNull

6e"nition=

!ong s=$IsN)$$Fmoca6ata%es  ResultSet Set,, s=$IsN)$$Fmoca6ata%es V Result moca6ata%ow, V Ro&"  Ro&"oin ointer  ter , char VColumn2ame VColumn2ameGG

6esc 6escrripti iption on==

his his func functi tion on retu return rns s a true true or fa!s fa!se e (a! (a!ue ue depending on whether or not the co!umn Bueried is a nu!! (a!ue.

%eturns=

%
amp!e= if sTlRs1ullres, row, BparrefB>> sprintfEuffer, BVhe parent reference is nullB><

185

C & I E N T

A C C E S S

* I A

M M D A

else sprintfEuffer, BVhe parent reference is FbsFB, char *> sTl2etWalueres, row, BparrefB>><

s;lReoveRo8

6e"nition=

(oid s=$Re%o,eRow Fmoca6ata%es V Result  ResultSet Set,, moca6ata%ow V Ro&"  Ro&"ointer  ointer G

6esc 6escrripti iption on==

his his func functi tion on is used used to remo remo(e (e the the gi( gi(en en row row from the gi(en resu!t set.

%eturns=

(oid

amp!e= sTl8emove8owres, row><

s;lSetDate

6e"nition=

!ong s=$Set4ateFmoca6ata%es s=$Set4ateFmoca6ata%es V Result  ResultSet Set,, moca6ata%ow V Ro&"  Ro&"ointer  ointer , char VColumn2ame VColumn2ame,, char Vdata VdataGG

6escr escrip ipttion= ion=

his his func functi tio on can can be used sed to to pr pro(id (ide a con(enient ca!!ing interface to updating data co!umns returned returned in an$ resu!t set. he co!umn in Buestion must eist and be of t$pe COMW&H6A.

%eturns=

)tatus of the function ca!! eI#*A/I6HA%4) eI#*A/I6HA%4)  Co!umn cou!d not be found eI#*A/I6HO&%AIO#  Co!umn is not of correct t$pe eO\ ' )uccess

amp!e= status = sTl0et#ateres, row, Bstart_dateB,   B'%%)%)'(%%%B><

s;lSet9loat

6e"nition=

!ong s=$Set$oatFmoca6ata%es s=$Set$oatFmoca6ata%es V Result  ResultSet Set,, moca6ata%ow V Ro&"  Ro&"ointer  ointer , char VColumn2ame VColumn2ame,, doub!e * alueG alueG

6escr escrip ipttion= ion=

his his func functi tio on can can be used sed to to pr pro(id (ide a con(enient ca!!ing interface to updating data co!umns returned returned in an$ resu!t set. he co!umn

186

C & I E N T

A C C E S S

* I A

M M D A

in Buestion must eist and be of t$pe COMW&H
)tatus of the function ca!! eI#*A/I6HA%4) eI#*A/I6HA%4)  Co!umn cou!d not be found eI#*A/I6HO&%AIO#  Co!umn is not of correct t$pe eO\ ' )uccess

amp!e= status = sTl0et;loatres, row, BamountB, '.'()><

s;lSet&on=

6e"nition=

!ong s=$Seton'Fmoca6ata%es s=$Seton'Fmoca6ata%es V Result  ResultSet Set,, moca6ata%ow V Ro&"  Ro&"ointer  ointer , char VColumn2ame VColumn2ame,, !ong FalueG FalueG

6escr escrip ipttion= ion=

his his func functi tio on can can be used sed to to pr pro(id (ide a con(enient ca!!ing interface to updating data co!umns returned returned in an$ resu!t set. he co!umn in Buestion must eist and be of t$pe COMW&H/O#4.

%eturns=

)tatus of the function ca!! eI#*A/I6HA%4) eI#*A/I6HA%4)  Co!umn cou!d not be found eI#*A/I6HO&%AIO#  Co!umn is not of correct t$pe eO\ ' )uccess

amp!e= status = sTl0et!on5res, row, BTuantityB, I'><

s;lSetStrin=

6e"nition=

!ong s=$SetStrin'Fmoca6ata%es s=$SetStrin'Fmoca6ata%es V Result  ResultSet Set,, moca6ata%ow V Ro&"  Ro&"ointer  ointer , char VColumn2ame VColumn2ame,, charV FalueG FalueG

6escr escrip ipttion= ion=

his his func functi tio on can can be used sed to to pr pro(id (ide a con(enient ca!!ing interface to updating data co!umns returned returned in an$ resu!t set. he co!umn in Buestion must eist and be of t$pe COMW&H)%I#4.

187

C & I E N T

A C C E S S

%eturns=

* I A

M M D A

)tatus of the function ca!! eI#*A/I6HA%4) eI#*A/I6HA%4)  Co!umn cou!d not be found eI#*A/I6HO&%AIO#  Co!umn is not of correct t$pe eO\ ' )uccess

amp!e= status = sTl0et0trin5res, row, BnameB, B0mithB><

OS En0apsulation &ibrar7 @oslib he O) encapsu!ation !ibrar$ or O) !ibrar$ encapsu!ates ca!!s to operat operating ing s$stem's s$stem'spec peci"c i"c faci!iti faci!ities es in a consis consisten tentt wa$. wa$. One major c!ass of functiona!it$ that is encapsu!ated in the O) !ibrar$ is interprocess communication using mai!boes, memor$'mapped "!es, and C& socets. In genera!, an$ O)'speci"c functiona!it$ functiona!it$ is dea!t with in the O) !ibrar$.

OS &ibrar7 Mailbo: 9un0tions he hese funct unctio ions ns a!!o a!!ow w the the mani manip pu!at u!atio ion n of a high high'! '!e( e(e! e! interp interpro roces cess s communic communicati ation on constru construct ct ca!!ed ca!!ed a mai!bo. mai!bo. A  mai! mai!bo bo  is a name named d enti entit$ t$ that that a!!o a!!ows ws an$ an$ proc proces ess s to send send messages, messages, which which a sing!e recei recei(ing (ing process process can recei recei(e. (e. he creat creating ing proces process s ca!!s ca!!s osM6Create  osM6Create   an and osM6Rec, , whi!e the sending process ca!!s osM6Send. osM6Send . ach ca!! to osM+3)end wi!! resu!t in a message being sent to the process that created the mai!bo. recei(ing (ing proces process, s, upon upon ca!!in ca!!ing g osM+3% osM+3%ec( ec( wi!! wi!! Ca,eat= Ca,eat= he recei wait fore(er unti! a message comes through Fun!ess it uses the O)HM+3 O)HM+3H#O H#O-AI PagEmo PagEmore re on that !aterG. !aterG. If a recei recei(ing (ing process wants to watch more than one incoming mai!bo or do wor between incoming messages, the event library  of  of routines shou!d be used instead. instead. It is intended for precise!$ precise!$ that purpose. purpose. osM%BCreate

6e"nition= 6escr escrip ipttion ion

 

osM6CreateFchar osM6CreateFchar Vm#*name Vm#*name,, !ong ma*_ms+G ma*_ms+G his his func functi tio on cre create ates a mai mai!b !bo o wit with h the the gi(e gi(en n name, and gi(es it a maimum message siXe of ma*_ms+. ma*_ms+. he m#*name parameter m#*name parameter must represent a uniBue mai!bo name that is has not  $et been been opened opened on the s$stem s$stem.. he ma*_ms+

188

C & I E N T

A C C E S S

* I A

M M D A

parameter shou!d be set to the siXe of the !argest message the recei(ing process wou!d e(er epect to get. %eturns=

On success, returns a pointer to an OSM6 structure that can be used in future ca!!s to  or osM6C$ose. osM6Rec,  or osM6C$ose. On fai!ure, return a #// pointer. pointer.
osM%BRe0v

6e"nition=

 

osM6Rec, FO)M+3 FO)M+3 Vm#* Vm#*,, (oid V#uer  V#uer , !ong si.e, si.e, !ong Vms+si.e Vms+si.e,, int Ha int Ha+s +sGG

6esc 6escrripti iption on==

his his func functi tion on wait waits s for for a mes messa sage ge to arri arri(e (e on the mai!bo m#*, m#*, which must be a mai!bo created with osM6Create and osM6Create  and returns that message in buer, up to si.e b$tes. If ms+si.e is non'nu!!, it is "!!ed in with the siXe of the message recei(ed. recei(ed. If the message that was sent sent was !arger than si.e, si.e, on!$ si.e b$tes si.e b$tes of the message are ept, and the rest of the message is discarded. ms+si.e, ms+si.e, howe(er, wi!! contain the origina! siXe of the message. he Ha he Ha+s +s parameter can ha(e the (a!ue 0 FXeroG or O)HM+3H#O-AI. O)HM+3H#O-AI. If the Ha the Ha+s +s parameter  parameter is set to O)HM+3H#O-AI, the function does not wait for a message to arri(e, and returns immediate!$, message or not.

%eturns=

eO\ on success. If If Ha+s  Ha+s has  has the (a!ue O)HM+3H#O-AI O)HM+3H#O-AI and no message is waiting to be read, eO)HIMO wi!! be returned.

amp!e=

his e eamp!e us uses an an im imaginar$ st structure ca ca!!ed myms+. myms+. he structure can be an$thing, but must be identica!!$ de"ned in the sending and recei(ing process. F)ee eamp!e at osM6Send be!owG osM6Send be!owG "0DO *mymES< struct myms5 messa5e< lon5 realsi4e< mymES = osDO9reateD6DCR!O", si4eof messa5e>< if L mymES> 

189

C & I E N T

A C C E S S

* I A

  A

M M D A

printfUnaEle to load mailEoSP bs, os7rror>>< eSit7RV_0U99700><

while e" == osDO8ecvmymES, ?messa5e, si4eof messa5e, ?realsi4e, %>>  if % == strncmpmessa5e.command, eSit, realsi4e>>   Erea3< M A osDO9losemymES><

osM%BRe0vTieout

6e"nition=

 

osM6Rec,3i%eo)tFO)M+3 osM6Rec,3i%eo)t FO)M+3 Vm#* Vm#*,, (oid V#uer , !ong si.e, si.e, !ong Vms+si.e Vms+si.e,, int timeoutG timeoutG

6esc 6escrripti iption on==

his his func functi tion on wait waits s for for a mes messa sage ge to arri arri(e (e on the mai!bo m#*, m#*, which must be a mai!bo created with osM6Create and osM6Create  and returns that message in buer, up to si.e b$tes. If ms+si.e is non'nu!!, it is "!!ed in with the siXe of the message recei(ed. recei(ed. If the message that was sent sent was !arger than si.e, si.e, on!$ si.e b$tes si.e b$tes of the message are ept, and the rest of the message is discarded. ms+si.e, ms+si.e, howe(er, wi!! contain the origina! siXe of the message. he timeout parameter is the number of seconds to wait for a message before timing out.

%eturns=

eO\ on success. If a timeout occurs, eO)HIMO wi!! be returned.

amp!e=

his e eamp!e us uses an an im imaginar$ st structure ca ca!!ed myms+. myms+. he structure can be an$thing, but must be identica!!$ de"ned in the sending and recei(ing process. F)ee eamp!e at osM6Send be!owG osM6Send be!owG "0DO *mymES< struct myms5 messa5e< lon5 realsi4e< mymES = osDO9reateD6DCR!O", si4eof messa5e>< if L mymES>  printfUnaEle to load mailEoSP bs, os7rror >><   eSit7RV_0U99700>< A

190

C & I E N T

A C C E S S

* I A

M M D A

while e" == osDO8ecvVimeoutmymES, ?messa5e, si4eof messa5e, ?realsi4e, '>>  if % == strncmpmessa5e.command, eSit,   realsi4e>>   Erea3< M A osDO9losemymES><

osM%BSend

6e"nition=

 

osM6SendFchar osM6SendFchar Vm#*name Vm#*name,, (oid V#uer  V#uer , !ong si.e, si.e, int Ha int Ha+s +sGG

6esc 6escrripti iption on==

his his func functi tion on send send the the mes messa sage ge cont contai aine ned d in in the the "rst si.e b$tes si.e b$tes of #uer , and sends it to the mai!bo named m#*name. m#*name. he Ha he Ha+s +s parameter  parameter can ha(e the (a!ue 0 FXeroG or O)HM+3H#O-AI. O)HM+3H#O-AI. If the Ha the Ha+s +s parameter  parameter is set to O)HM+3H#O-AI, the function does not wait if it can>t immediate!$ send the message due to a resource being temporari!$ una(ai!ab!e.

%eturns=

eO\ on success. If Ha If Ha+s +s has  has the (a!ue O)HM+3H#O-AI O)HM+3H#O-AI and the message cannot be immediate!$ sent, eO)HIMO wi!! be returned.

amp!e= struct myms5 messa5e< memsetmessa5e, ‘%’, si4eof messa5e>< strcpymessa5e.command, eSit>< if e" L= osDO0endD6DCR!O", ?messa5e, si4eof messa5e, %>> printfUnaEle to send messa5eP bsn, os7rror >><

osM%BClose

6e"nition=

 

Vm#*GG osM6C$oseFO)M+3 osM6C$oseFO)M+3 Vm#*

6esc 6escrripti iption on==

his his func functi tion on c!os c!oses es the the mai mai!b !bo o iden identi ti" "ed b$ m#*. m#*. It remo(es a!! s$stem resources associated with the mai!bo.

%eturns=

eO\ on success.

191

C & I E N T

A C C E S S

* I A

M M D A

osM%BJill

6e"nition=

 

osM6
6esc 6escrripti iption on==

his his func functi tion on c!os c!oses es the the mai mai!b !bo o iden identi ti" "ed b$ m#*. m#*.

%eturns=

eO\ on success.

OS &ibrar7 Meor76apped 9iles 9un0tions hese functions a!!ow the creation and use of memor$'mapped "!es for for imp!ementing imp!ementing shared memor$ memor$ between between processes. processes. he memor$'mapped "!e construct a!!ows a "!e to be accessed using memo memor$ r$ acce access sses es,, rath rather er than than "!e "!e IO IO meth method ods s Fope Fopen, n, read read,, write, etcG, and a!!ows mu!tip!e processes to ha(e a shared (iew of the "!e, in eect gi(ing those processes a shared memor$ address space.  An$ "!e can be shared shared.. A "!e "!e to to be mapped mapped can be create created d eith either er through norma! "!e IO means, or through the osCreateMapi$e function. osCreateMap9ile

6e"nition=

 

6escr escrip ipttion ion

 flename e, !ong si.eG si.eG osCreateMapi$eFchar osCreateMapi$eFchar V flenam his his func functi tio on cr create ates an an emp emptt$ "!e "!e name named d  flena  flename me of  of siXe siXe. If fle If flename name is  is speci"ed without a path Fno s!ashes or bacs!ashes, depending on the p!atformG, the "!e wi!! be created in the MOC the MOCA_M A_MEMBI EMBIR R director$.

%eturns=

eO\ on success.

osMap9ile

6e"nition= 6escript iption

 

osMapi$eFchar osMapi$eFchar V flena  flename me,, (oid VVmem VVmem,, !ong modeG modeG his function ma maps th the "!e nam named flena  flename me into  into the address space of the the ca!!ing process process he address chosen Fb$ the operating s$stemG wi!! be p!aced into the pointer (ariab!e passed as mem. mem. If mode is mode is O)HMA&MO6H%O, the "!e is mapped with read'on!$ read'on!$ permissions. permissions. If mode is mode is O)HMA&MO6H%-, the "!e is mapped with read and write write permissions. permissions. If fl If flena ename me is  is

192

C & I E N T

A C C E S S

* I A

M M D A

speci"ed without a path Fno s!ashes or bacs!ashes, depending on the p!atformG, the "!e wi!! be !ooed for in the MOC the MOCA_M A_MEMB EMBIR IR director$. director$. On some p!atforms p!atform s Fnotab!$ Fnotab! $ Q&'3 on &A'%I)C &A'%I)C 1.1 architecturesG, a "!e ma$ not be mapped more than once into a sing!e process. If such a mo(e is attempted, unepected resu!ts ma$ occur. occur. %eturns=

eO\ on success. mem wi!! mem wi!! point to the new memor$ !ocation.

osUnap9ile

6e"nition=

 

osn%api$eF(oid osn%api$eF(oid Vmem VmemGG

6escr escrip ipttion ion

his his func functi tio on re remo(e mo(es s th the map mappi ping ng of the shared memor$ pointed to b$ mem from mem from the address space of the ca!!ing process. process. his function does not c!ear the (ariab!e containing the (a!ue of mem, mem, so it wi!! contain an in(a!id pointer after the ca!! to osn%api$e. osn%api$e.
%eturns=

eO\ on success.

os&o0Me

6e"nition= 6esc 6escrripti iption on

 

osockMe%F(oid osockMe%F(oid VmemG his his func functi tion on pro( pro(id ides es a simp simp!e !e s$nc s$nchr hron oniX iXat atio ion n mechanism for the shared memor$ aspect of a memor$'mapped "!e. mem must mem must point to a memor$ region mapped b$ osMapi$e. osMapi$e. If this function is ca!!ed and the !oc is a(ai!ab!e, it returns immediate!$, and a process can be assured that no other process is modif$ing the memor$ unti! osn$ockMe% is ca!!ed. If the function is ca!!ed and the reBuested !oc is he!d b$ another process, this function wi!! not return unti! the !oc is a(ai!ab!e, either because the other process has eited or has ca!!ed osn$ockMe%. osn$ockMe% .

193

C & I E N T

A C C E S S

* I A

M M D A

 Note  Note= he !ocing mechanism in p!ace here is ad(isor$, ad(isor$, meaning another process can ignore the !oc if the programmer programmer chooses to. A!so, the mode of the !oc depends on the permissions with which the the memor$ was mapped. A read' on!$ mapping wi!! create a read !oc, which wi!! a!!ow the granting of other read !ocs, but not write !ocs. A readwrite readwrite mapping wi!! create a write !oc, which wi!! not a!!ow the granting of read or write !ocs.  Note  Note= If a program ca!!s osockMe%, osockMe% , it must re!ease the !oc using osn$ockMe%, osn$ockMe% , or other processes waiting for that !oc wi!! hang unti! it eits. It>s a!wa$s a good idea to minimiXe the amount of code between ca!!s to osockMe% and osn$ockMe%. osn$ockMe% .

%eturns=

eO\ on success.

osUnlo0Me

6e"nition=

 

osn$ockMe%F(oid osn$ockMe%F(oid VmemG

6escr escrip ipttion ion

his his fun func ctio tion un!o un!oc cs s the the me memor$ mor$ re region gion !oc !oce ed d with osockMe%. osockMe% . If an$ processes are waiting in os/ocMem, the !oc wi!! be handed out to the net waiting waiting process.
%eturns=

eO\ on success.

OS &ibrar7 TC!FI! and So0et So0et 9un0tions MOCA uses C&I& and socets for inter'machine commu communic nicati ation. on. In order order to simp!if$ simp!if$ the interfac interface e into into inter' inter' machin machine e commun communica icatio tion, n, some some of the option options s associ associate ated d with with socets and -in)oc programming ha(e been boi!ed down to a few functions. A socet endpoint endpoint is created created Fb$ the ser(erG using os3Cisten, os3Cisten, and connected to Fb$ the c!ientG using socet is written written to and and read from from using using os3CConnect. os3CConnect . he socet osSockRec,  and   and osSockSend FC& osSockSend FC& socets are fu!! dup!e, so both ends can be read from and written toG.
194

C & I E N T

A C C E S S

* I A

M M D A

osTC!&isten

6e"nition=

 

os3CistenF)OC\H<6 os3CistenF)OC\H<6 Vdesc Vdesc,, short port, port, int #ac(lo+, #ac(lo+, int reuseG reuseG

6esc 6escrripti iption on==

his his func functi tion on crea create tes s a soc soce et, t, bind binds s it it to to C& C& port number port, port, and enab!es incoming connections on that port, p!acing the !oca! socet in the /I)# state. state. he #ac(lo+ parameter de"nes the number of incoming connections that can be pending at a gi(en time. 4enera!!$ this number is set to 20 for most app!ications. he reuse parameter reuse parameter sets the socet option )OH%)A66%, which a!!ows a ser(er to start whi!e a !oca! address is sti!! in use. hat is a common need when socet connections are aborted, !ea(ing C& connections in the
%eturns=

eO\ on success.
osTC!Conne0t

6e"nition=

 

os3CConnectF)OC\H<6 os3CConnectF)OC\H<6 Vdesc Vdesc,, char Vhost Vhost,, short portG portG

6esc 6escrripti iption on==

his his func functi tion on cre creat ates es a soc soce et, t, and and conn connec ects ts to to the hostname For I& addressG identi"ed in host using C& port port. port. here must be a socet For other C& endpointG in the /I)# state for that port on the target machine

%eturns=

eO\ on success.
osSo0A00ept

6e"nition= 6esc 6escrripti iption on==

 

osSockAcceptF)OC\H<6 osSockAcceptF)OC\H<6 d  d,, )OC\H<6 Vne&dG ne&dG his his func functi tion on wai waits ts for for an an inco incomi ming ng con conne nect ctio ion n on the socet identi"ed b$ d b$  d,, and generates a new socet Fne&d F ne&dGG which represents the new connection. ne&d must ne&d must not be a nu!! pointer.

195

C & I E N T

A C C E S S

%eturns=

* I A

M M D A

eO\ on success.
osSo0Send

6e"nition=

 

6escription=

osSockSendF)OC\H<6 osSockSendF)OC\H<6 d  d,, (oid Vms+ Vms+,, int len, len, int Ha int Ha+s +sGG his function se sends len b$tes len b$tes of data in the buer pointed to b$ ms+ to ms+ to the socet at the other end of the connection identi"ed b$ d b$ d.. he connection must ha(e been estab!ished either b$ using os3Cisten and os3Cisten and osSockAccept to osSockAccept to accept an incoming connection, or b$ using os3CConnect to os3CConnect  to connect to a remote ser(er. here is a possibi!it$ that the function wi!! send fewer than len b$tes len b$tes to the remote socet. socet. If that happens, the ca!!ing program must eep trac of what was sent and where to resume the transfer. he Ha+ he Ha+s s parameter can be the bitwise O% of the fo!!owing (a!ues= O)H)OC\HOO+= use C& urgent mode to send the data. he data must be recei(ed in urgent mode. his is rare!$ used. O)H)OC\H#O-AI= O)H)OC\H#O-AI= do not wait for resources to become a(ai!ab!e before sending. sending. If this Pag Pag is set and no s$stem resources are a(ai!ab!e, )OC\H%%O% is returned, and osSockErrno wi!! osSockErrno wi!! return O)HA4AI#. O)HA4AI#.

%eturns=

he nu number of of b$ b$tes ac actua!!$ tr transmitted, or or )OC\H%%O% on error.
osSo0Re0v

6e"nition=

 

osSockRec, F)OC\H<6 d F)OC\H<6 d,, (oid Vms+ Vms+,, int len, len, int Ha int Ha+s +sGG

196

C & I E N T

A C C E S S

6escript iption=

* I A

M M D A

his fu function re recei(es up up to to len b$tes len b$tes of data into the buer pointed to b$ ms+ from ms+ from the socet at the other end of the connection identi"ed b$ d b$ d.. he connection must ha(e been estab!ished either b$ using os3Cisten os3CistenosSockAccept to osSockAccept to accept an incoming connection, or b$ using os3CConnect to os3CConnect  to connect to a remote ser(er. here is a possibi!it$ that the function wi!! recei(e fewer than len b$tes. If that happens, and the ca!!ing program epects more, it must eep trac of what was sent and where to resume the transfer. here is no corre$ation between ca!!s to os)oc)end on one side of a socet connection and resu!ts from os)oc%ec( on the other side ecept that a!! the data wi!! e(entua!!$ come through. #o guarantee is made that the data wi!! arri(e in one b!oc or in man$. he Ha+ he Ha+s s parameter can be the bitwise O% of the fo!!owing (a!ues= O)H)OC\HOO+= use C& urgent mode to recei(e the data. he data must ha(e been sent sent in urgent mode. his is rare!$ used. used. O)H)OC\H#O-AI= O)H)OC\H#O-AI= do not wait for data to become a(ai!ab!e before returning. If this Pag is set and no data are a(ai!ab!e on the connection, )OC\H%%O% is returned, and osSockErrno wi!! osSockErrno wi!! return O)HA4AI#. O)HA4AI#. his option is usefu! for checing to see if there>s data O)H)OC\H&\= 6o not remo(e data from the communication stream. stream. An$ data on the stream is ept there, so that future ca!!s to os)oc%ec( wi!! succeed, but a cop$ of the data is p!aced into ms+. ms+.

%eturns=

he number of b$tes actua!!$ recei(ed, or )OC\H%%O% on error.
197

C & I E N T

A C C E S S

* I A

M M D A

osSockErrno wi!! osSockErrno wi!! return O)HCO##%) on disconnect and O)HA4AI# on timeout. osSo0S/utdo8n

6e"nition=

 

osSockS)tdownF)OC\H<6 osSockS)tdownF)OC\H<6 d  dGG

6esc 6escrripti iption on==

his his func functi tion on shu shuts ts down down the the soc soce ett con conne nect ctio ion n identi"ed b$ d b$ d.. A ca!! shou!d be made to os)ocC!oseF G after ca!!ing os)oc)hutdownF G.

%eturns=

eO\ on success.
osSo0Close

6e"nition=

 

osSockC$oseF)OC\H<6 osSockC$oseF)OC\H<6 d  dGG

6esc 6escrripti iption on==

his his func functi tion on c!os c!oses es the the soc soce ett con conne nect ctio ion n identi"ed b$ d b$ d.. A ca!! shou!d be made to os)oc)hutdownF G if no more communication on the socet is going to be done b$ a peer process.

%eturns=

eO\ on success.
osSo0Address

6e"nition=

 

osSockAddressF)OC\H<6 osSockAddressF)OC\H<6 d,  d, char Voutstr, Voutstr, !ong si.e, short Vport VportGG

6esc 6escrripti iption on==

his his fun funct ctio ion n retu return rns s addr addres ess s info inform rmat atio ion n abou aboutt the socet identi"ed b$ d b$ d.. he I& address of the other end of the connection is stored into outstr , and the remote port number is stored into the (ariab!e pointed to b$ port. port. si.e is si.e is the siXe of the string pointed to b$ outstr .

%eturns=

eO\ on success.
osSo0Errno

6e"nition=

 

osSockErrnoF(oidG osSockErrnoF(oidG

198

C & I E N T

A C C E S S

* I A

M M D A

6esc 6escrripti iption on==

his his func functi tion on ret retur urns ns an an err error or code code desc descri ribi bing ng what sort of prob!em happened most recent!$.

%eturns=

A specia!iXed error code speci"c to the contet in which it is ca!!ed.
osSo0Error 

6e"nition=

 

osSockError F(oidG F(oidG

6esc 6escrripti iption on==

his his func functi tion on ret retur urns ns a stri string ng desc descri ribi bing ng wha whatt sort of prob!em happened most recent!$ in the socet subs$stem.

%eturns=

A pointer to a nu!!'terminated string. he string is stored in static memor$, memor$, so its (a!ue shou!d be considered (o!ati!e. (o!ati!e. If this function is used, the return (a!ue shou!d be copied to another string or printed immediate!$.

osSo0ait

6e"nition=

 

osSock>aitF)OC\H<6 osSock>aitF)OC\H<6 d,  d, int do_read int do_readGG

6esc 6escrripti iption on==

his his func functi tion on wait waits s for for soc socet et acti acti(i (it$ t$ Fi.e Fi.e.. <6H%A6^<6HACC&^<6HC/O)G <6H%A6^<6HACC&^<6HC /O)G on the -indows p!atform. p!atform. If doHread is non'Xero, it wi!! pee to see if an$ data eists on the socet and if so, return prior to checing for other acti(it$ of the socet socet as described described abo(e. his function does not do an$thing on the #I3 p!atform Fit is a noopG.

%eturns=

eO\ on socet acti(it$ or data eists on socet.
osSo0aitTieout

6e"nition= 6esc 6escrripti iption on==

 

F)OC\H<6 d,  d, int osSock>ait3i%eo)tF)OC\H<6 osSock>ait3i%eo)t timeoutG timeoutG his his func functi tion on wait waits s for for soc socet et acti acti(i (it$ t$ for for a predetermined number of seconds de"ned b$ timeout argument. argument. his is imp!emented on a!! p!atforms  the #I3 imp!ementation uses a

199

C & I E N T

A C C E S S

* I A

M M D A

se!ect and the -indows imp!ementation uses a  (ersio  (ersion n of of osSock>ait. osSock>ait. #O= his function was imp!emented to woraround an issue on -indows 2000 where the se!ect function wou!d return the -)AACC) error when a dierent thread attempted to wait Fi.e. se!ectG on a socet connection created b$ a dierent thread Fe.g. MOCA ser(er process and MOCA connection manager processG. #O= Current imp!ementation on!$ wors on one socet "!e descriptor. %eturns=

eO\ on on socet acti(it$ or or wh where da data eists on on socet. If no acti(it$ occurs occurs on socet socet before before the timeout occurs, eO)HIMO wi!! be returned.
OS &ibrar7 9iles7ste 9un0tions hese hese functi functions ons pro(ide pro(ide access access to a set of "!es$s "!es$stem tem're 're!at !ated ed functions. osC/dir 

6e"nition=

 

osCdir Fchar Fchar Vdirector$G

6esc 6escrripti iption on==

his his func functi tion on chan change ges s the the curr curren entt wor wori ing ng director$ for the ca!!ing process.

 %e  %eturns=

eO\ on success. rror code on fai!ure.

200

C & I E N T

A C C E S S

* I A

M M D A

osCreateDir 

6e"nition=

 

osCreate4ir Fchar Fchar Vdirector$G

6esc 6escrripti iption on==

his his fun funct ctio ion n crea create tes s the the gi(e gi(en n dire direct ctor or$ $ usin using g the defau!t ownership and permissions.

 %e  %eturns=

eO\ on success. rror code on fai!ure.

osReoveDir 

6e"nition=

 

Fchar Vdirector$G osRe%o,e4ir Fchar

6esc 6escrripti iption on==

his his func functi tion on rem remo( o(es es the the gi( gi(en en dire direct ctor or$ $.

 %e  %eturns=

eO\ on success. rror code on fai!ure.

osGetCurrentDir 

6e"nition=

 

F(oidG os:etC)rrent4ir F(oidG

6esc 6escrripti iption on==

his his func functi tion on gets gets the the curr curren entt wor wori ing ng director$. director$. he pointer returned b$ os4etCurrent6irF G is a!!ocated (ia a ca!! to ma!!ocF G and shou!d be freed to a(oid memor$ !eas.

 %et  %eturns=

A pointer to to the current wo woring di director$, otherwise #//.

OS &ibrar7 Mis0ellaneous 9un0tions here are some other operating s$stem faci!ities that we uti!iXe but ha(e diering diering under!$i under!$ing ng mechanisms. mechanisms. )ome of those those are made made a(ai a(ai!ab !ab!e !e in a port portab ab!e !e wa$ wa$ with with the the remai remaini ning ng os!i os!ib b functions. osSleep

6e"nition=

 

osS$eepFint osS$eepFint sec sec, int msecG msecG

6esc 6escrripti iption on==

his his func functi tion on mae maes s the the ca!! ca!!in ing g pro proce cess ss s!ee s!eep p for the time speci"ed. sec is sec is the number of seconds to s!eep, and msec is msec is the number of mi!!iseconds. he tota! time to s!eep is the sum of the two.

 %e  %eturns=

#othing.

201

C & I E N T

A C C E S S

* I A

M M D A

osError 

6e"nition=

 

6esc 6escrripti iption on==

osError F(oidG F(oidG his his func functi tion on ret retur urns ns a stri string ng desc descri ribi bing ng wha whatt sort of prob!em happened most recent!$ in s$stem areas other than the socet subs$stem.  A good good use for this this wou!d wou!d be in err error or messag messages es..

%eturns=

A pointer to a nu!!'terminated string. he string is stored in static memor$, memor$, so its (a!ue shou!d be considered (o!ati!e. (o!ati!e. If this function is used, the return (a!ue shou!d be copied to another string or printed immediate!$.

osGet*ar 

6e"nition=

 

os:etVar Fchar Fchar Vvar  Vvar G

6esc 6escrripti iption on==

his his func functi tion on retu return rns s the the (a!u (a!ue e of the the en(ironment (ariab!e var , or #// if the  (ariab  (ariab!e !e is is not not de"ne de"ned. d.

%eturns=

A po pointer to to a nu!!'terminated st string or or # #//. he string is stored in static memor$, so its  (a!ue  (a!ue shou shou!d !d be be cons conside idere red d (o!at (o!ati!e i!e.. If this this function is used, the return (a!ue shou!d be copied to another string or used immediate!$. immediate!$.

osGetRe=

6e"nition=

 

os:etRe'Fchar os:etRe'Fchar Vsection, Vsection, char  char Vname VnameGG

6esc 6escrripti iption on==

his his func functi tion on retu return rns s the the (a!u (a!ue e of of the the s$st s$stem em'' speci"c registr$ entr$ identi"ed b$ section and name. name. nder the -in82 subs$stem, the -indows %egistr$ is used FQ\WH/OCA/HMACQI#)oftware%edprairie MOCAMOCAH#*#AM or 6efau!tsection 6efau!tsectionname. name. nder #I3'based s$stems, a "!e is parsed Fin MOCAH%4I)%WG that contains sections e$s and (a!ues.

%eturns=

A pointer to a nu!!'terminated string. he string is stored in static memor$, memor$, so its (a!ue shou!d be considered (o!ati!e. (o!ati!e. If this function is used, the return (a!ue shou!d be copied to another string or used immediate!$.

202

C & I E N T

A C C E S S

* I A

M M D A

os!rint9ile

6e"nition=

 

osrinti$eFchar osrinti$eFchar V flena  flename me,, char Vdevice Vdevice,, int copies, copies, char Voptions VoptionsGG

6escr escrip ipttion= ion=

his his func functi tio on spoo! poo!s s the "!e fl !e flena ename me for  for printing on the print Bueue identi"ed b$ device. device. If device is device is #//, the s$stem defau!t printer is used. he copies parameter copies parameter speci"es how man$ copies are to be printed. printed. he options parameter options parameter speci"es other options to the speci"c printer.

%eturns=

eO\ on success.

osSnprintf 

6e"nition=

 

osSnprintf Fchar Fchar Vs Vs, int n, const char V mt,  mt, EG EG

6esc 6escrripti iption on==

his his func functi tion on is is ide ident ntic ica! a! to to spr sprin intf tfFF G wit with h the the addition of the argument n, which !imits the number of characters written to the buer s buer  s.. he buer s is a!wa$s nu!!'terminated.

%eturns=

he number of characters formatted, that is, the number of characters that wou!d ha(e been written to the buer s if it were !arge enough. If the (a!ue of n is 0, an unspeci"ed (a!ue !ess than 1 is returned.

Event &ibrar7 @evtlib he he e(en e(entt !ibr !ibrar ar$ $ pro( pro(id ides es a high high'! '!e( e(e! e! inte interrface face into into the the standard standard O)'!ibrar$ O)'!ibrar$ interproc interprocess ess communicati communication on mechanisms. mechanisms. he main purpose of the !ibrar$ is to pro(ide a mechanism to write e(ent'dri(en programs using mai!boes. Event &ibrar7 9un0tions

he basis of a!! the e(ent !ibrar$ functions is the MOCAH*# stru struct ctur ure. e. he he MOCA MOCAH H* *# # stru struct ctur ure e has has the the fo!! fo!!ow owin ing g members.  short type< lon5 iterate< lon5 *callEac3>>< lon5 user_data<

H* H* H* H*

Dust Ee a 3nown 7vent Vype *H Rterations, 7WV_;"87W78 or a  *H 9allEac3 function *H User defines what is here *H

lon5 time<

H* Vime in hundreths of a second

char name[7WV_QU71CD7_!71]< H* Ds5 Tueue or loc3 name

203

*H *H

C & I E N T

A C C E S S

* I A

M M D A

lon5 maS_si4e< void *data<

H* DaSimum si4e of read H* /tr to data @ event complete.

*H *H

7W71V_0V8 *event<

H* Rnternal event handlin5 struct *H

A

-hen a program wants to wor with e(ents, it must ha(e an arra arra$ $ of MOCA MOCAH H* *# # stru struct ctur ures es.. ach ach arra arra$ $ e!em e!emen entt represents one one e(ent that the process wants noti"cation noti"cation of. of. he "na! e!ement of the arra$ must be mared as the end of the arra$. arra$. /et>s go through the structure members indi(idua!!$ indi(idua! !$.. type

must be one of= *HIM%, *HM)4H%A6, *HM)4H%A6, *H6*H%A6, *H6*H%A6, *H*#H6O#. *H*#H6O#. he !ast !ast e!ement in the MOCAH*# arra$ must ha(e its type member type member set to *H*#H6O#. Current!$ *H6*H%A6 is unimp!emented and ha(ing an e(ent of that t$pe wi!! cause e,tRe=)est to e,tRe=)est to fai!.

iterate

%epresents the number of times this e(ent ma$ occur. occur. After a particu!ar particu! ar e(ent has occurred iterate times, iterate times, the e(t%ea!iXe function ends. 4enera!!$, it>s more usefu! to set iterate to *H
call#ac(

his is the function that gets ca!!ed when an e(ent occurs. he function gets ca!!ed with a pointer to the MOCAH*# structure itse!f as the on!$ parameter.

user_data

his can contain whate(er data the user wants. It is usefu! in situations where se(era! e(ents trigger a sing!e ca!!bac, and the same ca!!bac function must act on dierent data. data. In man$ cases, this member is set to the inde into the arra$ of MOCAH*# structures for the particu!ar e(ent.

time

F*HIM%H* on!$G his is the timeout period of the timer in hundredths of seconds.

name

F*HM)4H%A6 on!$G his is the name of the mai!bo to be opened and read from. his must be a nu!!'terminated string.

204

C & I E N T

A C C E S S

* I A

M M D A

ma*_si.e

F*HM)4H%A6 on!$G his is the siXe of the data b!oc passed in as the data structure data structure member.

data

F*HM)4H%A6 on!$G his is the data b!oc where the data from the mai!bo read goes to.

event

his is a structure that the e(ent !ibrar$ uses interna!!$. interna!!$. It contains some of the resources a!!ocated for the e(ent !ist, and shou!d ne(er be accessed b$ user programs.

evtRe;uest

6e"nition=

 

e,tRe=)estFMOCAH*# e,tRe=)estFMOCAH*# Vevt_array  Vevt_array G

6esc 6escrripti iption on==

his his fun funct ctio ion n a!!o a!!oca cate tes s reso resour urce ces s for for the the arra arra$ $ of MOCAH*# structures passed in evt_array . his inc!udes starting mai!boes and initia!iXing timers.

%eturns=

eO\ on success. If there is a prob!em, such as a mai!bo that>s a!read$ a!!ocated, then osError  can be used to get more speci"c error information.

amp!e=

he eamp!e be!ow sets up a mai!bo read on two mai!boes, using the same ca!!bac function Fnote the use of the user_data and user_data and data MOCAH*# structure membersG. here is a!so a timer function set to occur e(er$ two minutes F12000 F12000 hundredths hundredths of secondsG. A!! e(ents are set up to iterate fore(er. define define define define

C##D02_7W71V 8#VD02_7W71V VRD78_7W71V 71#_7W71V

define 1UD_7W71V0

%  ' ( )

define `8C##D28_DO `8C##D28DO define `8QU7D28_DO `8QU7D28DO define VRD7"UV

'%%%

H* ' minutes *H

D"9C_7W71V events[1UD_7W71V0]< events[C##D02_7W71V].type = 7WV_D02_87C#< events[C##D02_7W71V].iterate = 7WV_;"87W78< events[C##D02_7W71V].callEac3 = /rocessDs5< events[C##D02_7W71V].data = ?add_ms5< events[C##D02_7W71V].user_data = C##D02_7W71V<

205

C & I E N T

A C C E S S

* I A

M M D A

events[C##D02_7W71V].maS_si4e = si4eofDessa5eUnion>< sprintfevents[C##D02_7W71V].name, BbsB, `8C##D28_DO>< events[8#VD02_7W71V].type = 7WV_D02_87C#< events[8#VD02_7W71V].iterate = 7WV_;"87W78< events[8#VD02_7W71V].callEac3 = /rocessDs5< events[8#VD02_7W71V].data = ?in_ms5< events[8#VD02_7W71V].user_data = 8#VD02_7W71V< events[8#VD02_7W71V].maS_si4e = si4eofDessa5eUnion>< sprintfevents[8#VD02_7W71V].name, BbsB, `8QU7D28_DO>< events[VRD78_7W71V].type = 7WV_VRD78< events[VRD78_7W71V].time = VRD7"UV< events[VRD78_7W71V].iterate = 7WV_;"87W78< events[VRD78_7W71V].callEac3 = /rocessVmr< events[71#_7W71V].type = 7WV_7W71V_71#< if e" L= evtRequestevents>>  printf8eTuest failedP bsn, os7rror >><   eSit7RV_;CR!U87>< A M

evtRealie

6e"nition=

 

6esc 6escrripti iption on==

e,tRea$iBeFMOCAH*# e,tRea$iBeFMOCAH*# Vevt_array  Vevt_array G /oop /oop wait waitin ing g for for e(e e(ent nts s to to occ occur ur,, and and ca! ca!!! the the  (ariou  (arious s assoc associat iated ed ca!!ba ca!!bac c func functio tions ns when when the$ the$ do. do.

%eturns=

eO\ if we>(e eceeded the number of iterations for a particu!ar e(ent. If a ca!!bac returns returns an$thing other than eO\, that (a!ue is returned. Otherwise, this function ne(er returns.

amp!e=

FContinued from abo(eG M evtRealizeevent events>< s><

H* `e `e don’t don’t care care aEout aEout the status status

*H M

evt9reeEvents

6e"nition=

e(treeE,entsFMOCAH*# reeE,ents FMOCAH*# Ve(tHarra$G

6esc 6escrripti iption on==

his his fun funct ctio ion n free frees s res resou ourc rces es a!! a!!oc ocat ated ed for for the the !ist of e(ents. his must be ca!!ed after e(t%eBuest.

%eturns=

eO\ on success.

206

C & I E N T

A C C E S S

amp!e=

* I A

M M D A

FContinued from abo(eG M evtFreeEventsevents><

eSit7RV_0U99700><

MOCA BM& &ibrar7 @:llib he MOCA 3M/ !ibrar$ pro(ides a high'!e(e! interface into an 3M/ parserprocessor. parserprocessor. hese routines can be used to create new 3M/ docume documents nts,, tra(er tra(erse se eisti eisting ng 3M/ docume documents nts and app!$ app!$ st$!esheets to 3M/ documents. :lAddAttribute

6e"nition=

 

6escr escrip ipttion= ion=

%+%$AddAttri*)teFmm!Ctt %+%$AddAttri*)te Fmm!Ctt Vctt, mm!#ode Vparent, char Vname, char V(a!ueG Add an attr attrib ibut ute e as as a chi! chi!d d of of the the node node parent. parent . If parent is parent  is #//, add the attribute as a chi!d of the document e!ement.

 Argume  Arguments nts==

ctt ctt

3M/ parser parserpr proc ocess essor or sessio session n conte contet. t.   parent &arent node. name #ame of at attribute.  (a!ue  (a!ue *a!ue a!ue of of attri attribut bute. e.

%eturns=

&onter to a new attribute on success. #// on fai!ure.

amp!e= include :mSmlliE.hG mSml1ode *attr< attr = mSmlCddCttriEutectSt, node, unit, pounds>< if attr == 1U!!>  printf9ould not add attriEuten>< eSit7RV_;CR!U87>< A

:lAddCoent

6e"nition= 6escr escrip ipttion= ion=

 

%+%$AddCo%%entFmm!Ctt %+%$AddCo%%ent Fmm!Ctt Vctt, mm!#ode Vparent, char VcommentG Add a com comm ment ent as as a chi!d hi!d of the the node node parent. parent . If parent is parent  is #//, add the comment as a chi!d of the document e!ement. e!ement. If a document

207

C & I E N T

A C C E S S

* I A

M M D A

e!ement does not eist, add the comment as a chi!d of the document.  Argume  Arguments nts==

ctt ctt

3M/ parser parserpr proc ocess essor or sessio session n conte contet. t.   parent &arent node. comm mme ent et of co commen ment.

%eturns=

&onter to a new comment on success. #// on fai!ure.

amp!e= include :mSmlliE.hG mSml1ode *comment< comment = mSmlCdd9ommentctSt, 1U!!, my comment>< if comment == 1U!!>  printf9ould not add commentn>< eSit7RV_;CR!U87>< A

:lAddEleent

6e"nition= 6escr escrip ipttion= ion=

 Argume  Arguments nts==

%eturns=

 

%+%$AddE$e%entFmm!Ctt %+%$AddE$e%ent Fmm!Ctt Vctt, mm!#ode Vparent, char VnameG Add an e!em e!emen entt as as a chi!d hi!d of th the nod node e parent. parent. If parent is parent  is #//, add the e!ement as a chi!d of  the document document e!ement. If a document e!ement e!ement does not eist, mae the new e!ement the document e!ement. ctt ctt

3M/ parser parserpr proc ocess essor or sessio session n conte contet. t.   parent &arent node. name #ame of e! e!ement.

&onter to a new e!ement on success. #// on fai!ure.

amp!e= include :mSmlliE.hG mSml1ode *element< element = mSmlCdd7lementctSt, 1U!!, sample>< if element == 1U!!>  printf9ould not add elementn>< eSit7RV_;CR!U87><

208

C & I E N T

A C C E S S

* I A

M M D A

A

:lAdd!I

6e"nition=

 

6esc 6escrripti iption on==

%+%$AddIFmm!Ctt %+%$AddIFmm!Ctt Vctt, mm!#ode Vparent, char Vtarget, char VdataG Add Add a proc proces essi sing ng inst instru ruct ctio ion n as as a chi chi!d !d of the the node parent. parent. If parent is parent is #//, add the processing instruction as a chi!d of the document e!ement. e!ement. If a document e!ement does not eist, add the processing instruction as a chi!d of the document.

 Argume  Arguments nts==

ctt ctt

3M/ parser parserpr proc ocess essor or sessio session n conte contet. t.   parent &arent node. target &rocessing in instruction ta target. data &rocessing instruction data.

%eturns=

&onter to a new processing instruction on success. #// on fai!ure.

amp!e= include :mSmlliE.hG mSml1ode *pi< pi = mSmlCdd/RctSt, 1U!!, Sml, version=.%>< if pi == 1U!!>  printf9ould not add processin5 instructionn>< eSit7RV_;CR!U87>< A

:lAddTe:tNode

6e"nition= 6escr escrip ipttion= ion=

 Argume  Arguments nts==

 

%+%$Add3e+tNodeFmm!Ctt %+%$Add3e+tNode Fmm!Ctt Vctt, mm!#ode Vparent, char VtetG Add a te tett no node as a chi chi!d !d of the the node node parent. parent . If parent is parent  is #//, add the tet node as a chi!d of the document e!ement. ctt ctt tet

%eturns=

3M/ parser parserpr proc ocess essor or sessio session n conte contet. t.   parent &arent node. et to add.

&onter to a new tet node on success. #// on fai!ure.

209

C & I E N T

A C C E S S

* I A

M M D A

amp!e= include :mSmlliE.hG mSml1ode *teSt< teSt = mSmlCddVeSt1odectSt, element, some teSt>< if teSt == 1U!!>  printf9ould not add teSt noden>< eSit7RV_;CR!U87>< A

:lAppendC/ild

6e"nition=

 

6esc 6escrripti iption on==

%+%$AppendCi$dFmm!Ctt %+%$AppendCi$d Fmm!Ctt Vctt, mm!#ode Vparent, chi!dG Adds Adds the the nod node e chi chi!d !d to the the end end of the the !is !istt of of chi!dren of the node parent. If the chi!d is a!read$ in the tree, it is "rst remo(ed.

 Argume  Arguments nts==

ctt ctt

3M/ parser parserpr proc ocess essor or sessio session n conte contet. t.   parent &arent node. chi!d Chi!d to append.

%eturns=

&onter to the chi!d node on success. #// on fai!ure.

amp!e= include :mSmlliE.hG mSml1ode *new9hild< new9hild = mSmlCppend9hildctSt, parent, child>< if new9hild == 1U!!>  printf9ould not append childn>< eSit7RV_;CR!U87>< A

:lAppl7St7les/eet9ro9ile F :lAppl7St7les/eet9roStrin=

6e"nition=

 

Fmm!Ctt %+%$App$&St&$eseetro%i$eFmm!Ctt %+%$App$&St&$eseetro%i$e Vctt, char VpathnameG %+%$App$&St&$eseetro%Strin'Fmm!Ctt %+%$App$&St&$eseetro%Strin'Fmm!Ctt Vctt, char Vs!G

6esc 6escrripti iption on==

App! App!$ $ the the st$! st$!es eshe heet et from from the the gi(e gi(en n 3)/ 3)/ documentstring to the 3M/ in the gi(en parsing session.

210

C & I E N T

A C C E S S

* I A

M M D A

his function creates a new parsing session contet, which is the 3M/ that was generated after app!$ing the st$!esheet.  Argume  Arguments nts==

ctt ctt

3M/ parser parserpr proc ocess essor or sessio session n conte contet. t. pathname &athname of 3)/ document. s! 3)/ string.

%eturns=

&onter to a new contet on success. #// on fai!ure.

amp!e= include :mSmlliE.hG mSml9tSt *new< new = mSmlCplly0tylesheet;rom;ilectSt, cPfoo.Ssl>< if new == 1U!!>  printf9ould not apply stylesheetn>< eSit7RV_;CR!U87>< A

:lCloneNode

6e"nition= 6esc 6escrripti iption on==

 Argume  Arguments nts==

%eturns=

 

%+%$C$oneNodeFmm!Ctt %+%$C$oneNodeFmm!Ctt Vctt, mm!#ode Vnode, !ong deepG C!on C!ones es the the gi(e gi(en n node node.. he he c!on c!oned ed node node has has no parent. C!oning an e!ement copies a!! attributes and their (a!ues, inc!uding those generated b$ the 3M/ processor to represent defau!ted attributes, but this method does not cop$ an$ tet it contains un!ess it is a deep c!one, since the tet is contained in a chi!d tet node. C!oning an attribute direct!$, direct!$, as opposed to c!oning it as part of an e!ement c!oning operation, returns a speci"ed attribute Fspeci"ed is is trueG. C!oning an$ other t$pe of node simp!e$ c!ones a cop$ of the node. ctt ctt

3M/ parser parserpr proc ocess essor or sessio session n conte contet. t.   node #ode to c!one. dee deep
211

C & I E N T

A C C E S S

* I A

M M D A

amp!e= include :mSmlliE.hG mSml1ode *clone< clone = mSml9lone1odectSt, node, >< if clone == 1U!!>  printf9ould not clone noden>< eSit7RV_;CR!U87>< A

:lCreateAttribute

6e"nition=

 

6esc 6escrripti iption on==

%+%$CreateAttri*)teFmm!Ctt %+%$CreateAttri*)te Fmm!Ctt Vctt, char VnameG Crea Create tes s an attr attrib ibut ute e of the the gi(e gi(en n name name..

 Argume  Arguments nts==

ctt ctt

%eturns=

3M/ parser parserpr proc ocess essor or sessio session n conte contet. t.   name #ame of attribute.

&onter to a new attribute node on success. #// on fai!ure.

amp!e= include :mSmlliE.hG mSml1ode *attriEute< attriEute = mSml9reateCttriEutectSt, units>< if attriEute == 1U!!>  printf9ould not create attriEuten>< eSit7RV_;CR!U87>< A

:lCreateCDATASe0tion

6e"nition= 6esc 6escrripti iption on==  Argume  Arguments nts==

%eturns=

 

Fmm!Ctt Vctt, %+%$CreateC4A3ASectionFmm!Ctt %+%$CreateC4A3ASection char VdataG Crea Create tes s a new new C6A C6AA sec secti tion on node node whos whose e (a! (a!ue ue is the speci"ed string. ctt ctt

3M/ parser parserpr proc ocess essor or sessio session n conte contet. t.   data Character data.

&onter to a new C6AA section node on success. #// on fai!ure.

amp!e= include :mSmlliE.hG

212

C & I E N T

A C C E S S

* I A

M M D A

mSml1ode *cdata1ode< cdata1ode = mSml9reate9#CVC0ectionctSt, data>< if cdata1ode == 1U!!>  printf9ould not create 9#CVC sectionn>< eSit7RV_;CR!U87>< A

:lCreateCoent

6e"nition=

 

6esc 6escrripti iption on==

Fmm!Ctt Vctt, char %+%$CreateCo%%entFmm!Ctt %+%$CreateCo%%ent VcommentG Crea Create tes s a new new comm commen entt node node with with the the gi(e gi(en n comment.

 Argume  Arguments nts==

ctt ctt

3M/ parser parserpr proc ocess essor or sessio session n conte contet. t. comm commen entt et et of comment.

%eturns=

&onter to a new comment node on success. #// on fai!ure.

amp!e= include :mSmlliE.hG mSml1ode *comment1ode< comment1ode = mSml9reate9ommentctSt, my comment>< if comment1ode == 1U!!>  printf9ould not create comment noden>< eSit7RV_;CR!U87>< A

:lCreateDo0uent

6e"nition= 6escr escrip ipttion= ion=  Argume  Arguments nts== %eturns=

 

%+%$Create4oc)%entFmm!Ctt VcttG %+%$Create4oc)%entFmm!Ctt Crea Create te an 3M/ 3M/ docum ocumen entt objec bject. t. ctt ctt

3M/ parser parserpr proc ocess essor or sessio session n conte contet. t.

&onter to a new document node on success. #// on fai!ure.

amp!e= include :mSmlliE.hG mSml1ode *document< document = mSml9reate#ocumentctSt>< if document == 1U!!>

213

C & I E N T

A C C E S S

* I A

M M D A

 printf9ould not create documentn>< eSit7RV_;CR!U87>< A

:lCreateDo0uent9ra=ent

6e"nition=

 

6escr escrip ipttion= ion=

Fmm!Ctt %+%$Create4oc)%entra'%entFmm!Ctt %+%$Create4oc)%entra'%ent VcttG Crea Create tes s an emp emptt$ docu docume ment nt fra fragm gmen ent. t.

 Argume  Arguments nts==

ctt ctt

%eturns=

3M/ parser parserpr proc ocess essor or sessio session n conte contet. t.

&onter to a new document fragment node on success. #// on fai!ure.

amp!e= include :mSmlliE.hG mSml1ode *doc;ra5ment< doc;ra5ment = mSml9reate#ocument;ra5mentctSt>< if doc;ra5ment == 1U!!>  printf9ould not create document fra5mentn>< eSit7RV_;CR!U87>< A

:lCreateEleent

6e"nition= 6escr escrip ipttion= ion=  Argume  Arguments nts== %eturns=

 

%+%$CreateE$e%entFmm!Ctt %+%$CreateE$e%ent Fmm!Ctt Vctt, char VnameG Crea Create tes s an an e!e e!eme ment nt of the gi(e gi(en n nam name e. ctt ctt name

3M/ parser parserpr proc ocess essor or sessio session n conte contet. t. #ame of e!ement.

&onter to a new e!ement node on success. #// on fai!ure.

amp!e= include :mSmlliE.hG mSml1ode *element< element = mSml9reate7lementctSt, my name>< if element == 1U!!>  printf9ould not create elementn>< eSit7RV_;CR!U87>< A

214

C & I E N T

A C C E S S

* I A

M M D A

:lCreate!I

6e"nition=

 

6esc 6escrripti iption on==

%+%$CreateIFmm!Ctt %+%$CreateIFmm!Ctt Vctt, char Vtarget, char VdataG Crea Create tes s a new new proc proces essi sing ng inst instru ruct ctio ion n node node with with the gi(en target and data.

 Argume  Arguments nts==

ctt ctt target data

%eturns=

3M/ parser parserpr proc ocess essor or sessio session n conte contet. t. &rocessing in instruction ta target. &rocessing in instruction da data.

&onter to a new processing instruction node on success. #// on fai!ure.

amp!e= include :mSmlliE.hG mSml1ode *pi1ode< pi1ode = mSml9reate/RctSt, Sml, version=.%>< if pi1ode == 1U!!>  printf9ould not create pin>< eSit7RV_;CR!U87>< A

:lCreateTe:tNode

6e"nition=

 

6esc 6escrripti iption on==

%+%$Create3e+tNodeFmm!Ctt %+%$Create3e+tNode Fmm!Ctt Vctt, char VtetG Crea Create tes s a new new te tett nod node e wit with h the the gi(e gi(en n te tet. t.

 Argume  Arguments nts==

ctt ctt tet

%eturns=

3M/ parser parserpr proc ocess essor or sessio session n conte contet. t. et of tet node.

&onter to a new tet node on success. #// on fai!ure.

amp!e= include :mSmlliE.hG mSml1ode *teSt1ode< teSt1ode = mSml9reateVeSt1odectSt, my teSt>< if teSt1ode == 1U!!>  printf9ould not create teSt noden>< eSit7RV_;CR!U87>< A

:lErrorNuber 

6e"nition=

 

%+%$ErrorN)%*er Fmm!Ctt Fmm!Ctt VcttG

215

C & I E N T

A C C E S S

6esc 6escrripti iption on==

* I A

M M D A

4ets 4ets the the err error or numb number er asso associ ciat ated ed with with the the !as !astt error.

 Argume  Arguments nts==

ctt ctt

%eturns=

3M/ parser parserpr proc ocess essor or sessio session n conte contet. t.

rror number.

amp!e= include :mSmlliE.hG mSml1ode *document< document = mSml/arse;ilectSt, cPfoo.Sml>< if document == 1U!!>  printfbs $ bsn, mSml7rror1umEerctSt>,   mSml7rrorVeStctSt>>< eSit7RV_;CR!U87>< A

:lErrorTe:t

6e"nition=

 

6esc 6escrripti iption on==

%+%$Error3e+tFmm!Ctt %+%$Error3e+tFmm!Ctt VcttG 4ets 4ets the the err error or tet tet asso associ ciat ated ed with with the the !as !astt error.

 Argume  Arguments nts==

ctt ctt

%eturns=

3M/ parser parserpr proc ocess essor or sessio session n conte contet. t.

rror tet.

amp!e= include :mSmlliE.hG mSml1ode *document< document = mSml/arse;ilectSt, cPfoo.Sml>< if document == 1U!!>  printfbs $ bsn, mSml7rror1umEerctSt>,   mSml7rrorVeStctSt>>< eSit7RV_;CR!U87>< A

:lGetAttribute

6e"nition= 6escr escrip ipttion= ion=  Argume  Arguments nts==

 

%+%$:etAttri*)teFmm!Ctt %+%$:etAttri*)te Fmm!Ctt Vctt, mm!#ode Vnode, char VnameG 4et 4ets an an att attribut ibute e (a! (a!ue b$ name name.. ctt ctt node name

3M/ parser parserpr proc ocess essor or sessio session n conte contet. t. #ode to get attribute from. #ame of attribute.

216

C & I E N T

A C C E S S

%eturns=

* I A

M M D A

&onter to the attribute (a!ue on success. #// on fai!ure.

amp!e= include :mSmlliE.hG char *value< value = mSml2etCttriEutectSt, node, units>< if value == 1U!!>  printf9ould not 5et attriEute valuen>< eSit7RV_;CR!U87>< A

:lGetAttributeNode

6e"nition=

 

6escr escrip ipttion= ion=

Fmm!Ctt Vctt, %+%$:etAttri*)teNodeFmm!Ctt %+%$:etAttri*)teNode mm!#ode Vnode, char VnameG 4et 4ets an an att attribut ibute e node node b$ name ame.

 Argume  Arguments nts==

ctt ctt node name

%eturns=

3M/ parser parserpr proc ocess essor or sessio session n conte contet. t. #ode to get attribute node from. #ame of attribute.

&onter to the attribute node on success. #// on fai!ure.

amp!e= include :mSmlliE.hG mSml1ode *attr< attr = mSml2etCttriEute1odectSt, node, units>< if attr == 1U!!>  printf9ould not 5et attriEute noden>< eSit7RV_;CR!U87>< A

:lGetAttributes

6e"nition= 6esc 6escrripti iption on==  Argume  Arguments nts== %eturns=

 

%+%$:etAttri*)tesFmm!Ctt %+%$:etAttri*)tes Fmm!Ctt Vctt, mm!#ode VnodeG 4ets 4ets the the !is !istt of of att attri ribu bute tes s for for this this node node.. ctt ctt node

3M/ parser parserpr proc ocess essor or sessio session n conte contet. t. #ode to get attributes from.

&onter to the attribute !ist on success. #// on fai!ure.

amp!e=

217

C & I E N T

A C C E S S

* I A

M M D A

include :mSmlliE.hG mSml1ode!ist attriEutes< attriEutes = mSml2etCttriEutesctSt, node>< if attriEutes == 1U!!>  printf9ould not 5et attriEutesn>< eSit7RV_;CR!U87>< A

:lGetAttrNae

6e"nition=

 

6escr escrip ipttion= ion=

Fmm!Ctt Vctt, %+%$:etAttrNa%eFmm!Ctt %+%$:etAttrNa%e mm!#ode VattrG 4et 4ets the the name name of the the gi(e gi(en n att attri ribu bute te..

 Argume  Arguments nts==

ctt ctt attr

%eturns=

3M/ parser parserpr proc ocess essor or sessio session n conte contet. t. Attribute node to get name from.

&onter to the attribute name on success. #// on fai!ure.

amp!e= include :mSmlliE.hG char *name< name = mSml2etCttr1amectSt, attr>< if name == 1U!!>  printf9ould not 5et attriEute namen>< eSit7RV_;CR!U87>< A

:lGetAttrSpe0ified

6e"nition= 6esc 6escrripti iption on==

 Argume  Arguments nts==

%eturns=

 

%+%$:etAttrSpeci/edFmm!Ctt %+%$:etAttrSpeci/ed Fmm!Ctt Vctt, mm!#ode VattrG 4ets 4ets whet whethe herr or or not not the the gi( gi(en en attr attrib ibut ute> e>s s (a!u (a!ue e was ep!icit!$ speci"ed in the origina! document. ctt ctt attr from.

3M/ parser parserpr proc ocess essor or sessio session n conte contet. t. Attribute node to get information

1  Attribute was speci"ed. 0  Attribute was not speci"ed.

amp!e= include :mSmlliE.hG

218

C & I E N T

A C C E S S

* I A

M M D A

lon5 specd< specd = mSml2etCttr0pecifiedctSt, attr>< if specd == >  printfCttriEute was specifiedn>< eSit7RV_;CR!U87>< A

:lGetAttr*alue

6e"nition=

 

6esc 6escrripti iption on==

%+%$:etAttrVa$)eFmm!Ctt %+%$:etAttrVa$)e Fmm!Ctt Vctt, mm!#ode VattrG 4ets 4ets the the (a!u (a!ue e of the the gi(e gi(en n attr attrib ibut ute. e.

 Argume  Arguments nts==

ctt ctt attr

%eturns=

3M/ parser parserpr proc ocess essor or sessio session n conte contet. t. Attribute node to get (a!ue from.

&onter to the attribute (a!ue on success. #// on fai!ure.

amp!e= include :mSmlliE.hG char *value< value = mSml2etCttrWaluectSt, attr>< if value == 1U!!>  printf9ould not 5et attriEute valuen>< eSit7RV_;CR!U87>< A

:lGetC/ara0terData

6e"nition= 6esc 6escrripti iption on==  Argume  Arguments nts== %eturns=

 

%+%$:etCaracter4ataFmm!Ctt %+%$:etCaracter4ata Fmm!Ctt Vctt, mm!#ode VnodeG 4ets 4ets the the cha chara ract cter er data data for for thi this s C6A C6A A or or te tett node. ctt ctt node

3M/ parser parserpr proc ocess essor or sessio session n conte contet. t. #ode to get character data from.

&onter to the character data on success. #// on fai!ure.

amp!e= include :mSmlliE.hG char *data< data = mSml2et9haracter#atactSt, node>< if data == 1U!!> 

219

C & I E N T

A C C E S S

* I A

M M D A

printf9ould not 5et character datan>< eSit7RV_;CR!U87>< A

:lGetC/ara0terData&en=t/

6e"nition=

 

6esc 6escrripti iption on==

Fmm!Ctt %+%$:etCaracter4ataen'tFmm!Ctt %+%$:etCaracter4ataen't Vctt, mm!#ode VnodeG 4ets 4ets the the !eng !ength th of this this char charac acte terr data data..

 Argume  Arguments nts==

ctt ctt node from.

%eturns=

3M/ parser parserpr proc ocess essor or sessio session n conte contet. t. Character data node to get !ength

Character data !ength on on su success. rror code on fai!ure.

amp!e= include :mSmlliE.hG lon5 len5th< len5th = mSml2et9haracter#ata!en5thctSt, node>< if len5th : %>  printf9ould not 5et len5thn>< eSit7RV_;CR!U87>< A

:lGetC/ildNodes

6e"nition= 6esc 6escrripti iption on==  Argume  Arguments nts== %eturns=

 

%+%$:etCi$dNodesFmm!Ctt %+%$:etCi$dNodes Fmm!Ctt Vctt, mm!#ode VnodeG 4ets 4ets the the !is !istt of of chi chi!d !d node nodes s for for this this node node.. ctt ctt node

3M/ parser parserpr proc ocess essor or sessio session n conte contet. t. #ode to get chi!d nodes from.

&onter to the chi!d nodes on success. #// on fai!ure.

amp!e= include :mSmlliE.hG mSml1ode!ist child1odes< child1odes = mSml2et9hild1odesctSt, node>< if child1odes == 1U!!>  printf9ould not 5et child nodesn>< eSit7RV_;CR!U87>< A

220

C & I E N T

A C C E S S

* I A

M M D A

:lGetDo0uent

6e"nition=

 

6esc 6escrripti iption on==

%+%$:et4oc)%entFmm!Ctt VcttG %+%$:et4oc)%entFmm!Ctt 4et 4et the the docu docume ment nt asso associ ciat ated ed with with the the gi( gi(en en contet.

 Argume  Arguments nts==

ctt ctt

%eturns=

3M/ parser parserpr proc ocess essor or sessio session n conte contet. t.

&onter to the document node on success. #// on fai!ure.

amp!e= include :mSmlliE.hG mSml1ode *document< document = mSml2et#ocumentctSt>< if document == 1U!!>  printf9ould not 5et documentn>< eSit7RV_;CR!U87>< A

:lGetDo0uentEleent

6e"nition=

 

6esc 6escrripti iption on==

%+%$:et4oc)%entE$e%entFmm!Ctt VcttG %+%$:et4oc)%entE$e%entFmm!Ctt 4ets 4ets the the root root e!em e!emen entt of the the docu docume ment nt..

 Argume  Arguments nts==

ctt ctt

%eturns=

3M/ parser parserpr proc ocess essor or sessio session n conte contet. t.

&onter to the document e!ement node on success. #// on fai!ure.

amp!e= include :mSmlliE.hG mSml1ode *element< element = mSml2et#ocument7lementctSt>< if element == 1U!!>  printf9ould not 5et root elementn>< eSit7RV_;CR!U87>< A

:lGetEleents%7Ta=Nae

6e"nition= 6esc 6escrripti iption on==

 

Fmm!Ctt %+%$:etE$e%ents6&3a'Na%eFmm!Ctt %+%$:etE$e%ents6&3a'Na%e Vctt, mm!#ode Vparent, char VnameG 4ets 4ets a nod node e !is !istt of of a!! a!! desc descen enda dant nt e!em e!emen ents ts with with of the gi(en tag name, in the order in which the$ are encountered in a preorder tra(era! of this e!ement tree.

221

C & I E N T

A C C E S S

 Argume  Arguments nts==

* I A

M M D A

ctt ctt parent name

%eturns=

3M/ parser parserpr proc ocess essor or sessio session n conte contet. t. &arent node to use in search. ag name to search for. for.

&onter to the e!ements on success. #// on fai!ure.

amp!e= include :mSmlliE.hG mSml1ode!ist *elements< elements = mSml2et7lementsOyVa51amectSt, node, me>< if elements == 1U!!>  printf9ould not 5et elements Ey ta5 namen>< eSit7RV_;CR!U87>< A

:lGet9irstC/ild F :lGet&astC/ild

6e"nition=

 

%+%$:etirstCi$dFmm!Ctt %+%$:etirstCi$d Fmm!Ctt Vctt, mm!#ode VparentG %+%$:etastCi$dFmm!Ctt Vctt, %+%$:etastCi$dFmm!Ctt mm!#ode VparentG

6esc 6escrripti iption on==

4ets 4ets the the "rst rst!a !ast st chi! chi!d d of of this this node node..

 Argume  Arguments nts==

ctt ctt parent

%eturns=

3M/ parser parserpr proc ocess essor or sessio session n conte contet. t. &arent node to use in search.

&onter to the chi!d node on success. #// on fai!ure.

amp!e= include :mSmlliE.hG mSml1ode *first9hild< first9hild = mSml2et;irst9hildctSt, node>< if first9hild == 1U!!>  printf9ould not 5et first childn>< eSit7RV_;CR!U87>< A

:lGetIte

6e"nition= 6esc 6escrripti iption on==

 

%+%$:etIte%Fmm!Ctt %+%$:etIte%Fmm!Ctt Vctt, mm!#ode/ist Vnode/ist, !ong indeG 4ets 4ets the the inde indee ed d node node from from this this node node !ist !ist.. he he node !ist is 0 based.

222

C & I E N T

A C C E S S

 Argume  Arguments nts==

* I A

M M D A

ctt ctt 3M/ parser parserpr proc ocess essor or sessio session n conte contet. t. node/ist node/ist #ode !ist !ist to get item item from. inde Inde of of no node to to ge get.

%eturns=

&onter to the node on success. #// on fai!ure.

amp!e= include :mSmlliE.hG mSml1ode *node< node = mSml2etRtemctSt, node!ist, >< if node == >  printf9ould not 5et noden>< eSit7RV_;CR!U87>< A

:lGetNaedIte

6e"nition=

 

6esc 6escrripti iption on==

%+%$:etNa%edIte%Fmm!Ctt %+%$:etNa%edIte% Fmm!Ctt Vctt, mm!#ode/ist Vnode/ist, char VnameG 4ets 4ets the the name named d node node fro from thi this s node node !ist !ist..

 Argume  Arguments nts==

ctt ctt 3M/ parser parserpr proc ocess essor or sessio session n conte contet. t. node/ist node/ist #ode !ist !ist to get item item from. name #ame of node to get.

%eturns=

&onter to the node on success. #// on fai!ure.

amp!e= include :mSmlliE.hG mSml1ode *node< node = mSml2et1amedRtemctSt, node!ist, my name>< if node == 1U!!>  printf9ould not 5et noden>< eSit7RV_;CR!U87>< A

:lGetNe:tSiblin= F :lGet!reviousSiblin=

6e"nition=

 

%+%$:etNe+tSi*$in'Fmm!Ctt %+%$:etNe+tSi*$in' Fmm!Ctt Vctt, mm!#ode VnodeG %+%$:etre,io)sSi*$in'Fmm!Ctt Vctt, %+%$:etre,io)sSi*$in'Fmm!Ctt mm!#ode VnodeG

6escr escrip ipttion= ion=

4et 4ets the the net net sib sib!ing !ing of th this node. ode.

223

C & I E N T

A C C E S S

 Argume  Arguments nts==

* I A

ctt ctt node

%eturns=

M M D A

3M/ parser parserpr proc ocess essor or sessio session n conte contet. t. #ode to get sib!ing for.

&onter to the node on success. #// on fai!ure.

amp!e= include :mSmlliE.hG mSml1ode *siElin5< siElin5 = mSml2et1eSt0iElin5ctSt, node>< if siElin5 == 1U!!>  printf9ould not 5et neSt siElin5n>< eSit7RV_;CR!U87>< A

:lGetNode&ist&en=t/

6e"nition=

 

6esc 6escrripti iption on==

%+%$Nodeisten'tFmm!Ctt %+%$Nodeisten't Fmm!Ctt Vctt, mm!#ode/ist Vnode/istG 4ets 4ets the the num numbe berr of node nodes s in in thi this s no node !ist !ist

 Argume  Arguments nts==

ctt ctt 3M/ parser parserpr proc ocess essor or sessio session n conte contet. t. node/ist node/ist #ode !ist to get get !ength of. of.

%eturns=

/ength of the node !ist. rror code on fai!ure.

amp!e= include :mSmlliE.hG lon5 len5th< len5th = mSml2et1ode!ist!en5thctSt, ndoe!ist>< if len5th : %>  printf9ould not 5et node list len5thn>< eSit7RV_;CR!U87>< A

:lGetNodeNae

6e"nition= 6escript iption=  Argume  Arguments nts== %eturns=

 

Fmm!Ctt Vctt, %+%$:etNodeNa%eFmm!Ctt %+%$:etNodeNa%e mm!#ode VnodeG 4ets th the na name of of th this no node. ctt ctt node

3M/ parser parserpr proc ocess essor or sessio session n conte contet. t. #ode to get the name of.

&onter to the node name on success. #// on fai!ure.

224

C & I E N T

A C C E S S

* I A

M M D A

amp!e= include :mSmlliE.hG char *name< name = mSml2et1ode1amectSt, node>< if name == 1U!!>  printf9ould not 5et node namen>< eSit7RV_;CR!U87>< A

:lGetNode*alue

6e"nition=

 

6escript iption=

%+%$:etNodeVa$)eFmm!Ctt %+%$:etNodeVa$)e Fmm!Ctt Vctt, mm!#ode VnodeG 4ets th the (a (a!ue of thi this s no node. de.

 Argume  Arguments nts==

ctt ctt node

%eturns=

3M/ parser parserpr proc ocess essor or sessio session n conte contet. t. #ode to get the (a!ue of.

&onter to the node (a!ue on success. #// on fai!ure.

amp!e= include :mSmlliE.hG char *value< value = mSml2et1odeWaluectSt, node>< if value == 1U!!>  printf9ould not 5et node valuen>< eSit7RV_;CR!U87>< A

:lGetNodeT7pe

6e"nition= 6escr escrip ipttion= ion=  Argume  Arguments nts== %eturns=

 

Fmm!Ctt Vctt, %+%$:etNode3&peFmm!Ctt %+%$:etNode3&pe mm!#ode VnodeG 4et 4et the the node node t$pe $pe of this his node node.. ctt ctt node

3M/ parser parserpr proc ocess essor or sessio session n conte contet. t. #ode to get the t$pe of.

#ode t$pe on success. rror code on fai!ure.

amp!e= include :mSmlliE.hG mSml1odeVype nodeVype< nodeVype = mSml2et1odeVypectSt, node><

225

C & I E N T

A C C E S S

* I A

M M D A

if nodeVype == DD!_1"#7_V6/7_788"8>  printf9ould not 5et node typen>< eSit7RV_;CR!U87>< A

:lGet!arentNode

6e"nition=

 

6escr escrip ipttion= ion=

Fmm!Ctt Vctt, %+%$:etarentNodeFmm!Ctt %+%$:etarentNode mm!#ode Vchi!dG 4et 4ets the the par parent ent no node of thi this s nod node e.

 Argume  Arguments nts==

ctt ctt chi!d

%eturns=

3M/ parser parserpr proc ocess essor or sessio session n conte contet. t. #ode to get the parent of.

&onter to the parent node on success. #// on fai!ure.

amp!e= include :mSmlliE.hG mSml1ode *parent< parent = mSml2et/arent1odectSt, node>< if parent == 1U!!>  printf9ould not 5et parent noden>< eSit7RV_;CR!U87>< A

:lGet!IData

6e"nition= 6esc 6escrripti iption on==  Argume  Arguments nts==

%eturns=

 

%+%$:etI4ataFmm!Ctt %+%$:etI4ataFmm!Ctt Vctt, mm!#ode VpiG 4ets 4ets the the dat data a for for thi this s proc proces essi sing ng inst instru ruct ctio ion. n. ctt ctt 3M/ parser parserpr proc ocess essor or sessio session n conte contet. t. pi #ode to get the processing instruction data from. &onter to to th the pr processing in instruction da data on on success. #// on fai!ure.

amp!e= include :mSmlliE.hG char *data< data = mSml2et/R#atactSt, pi>< if data == 1U!!>  printf9ould not 5et datan>< eSit7RV_;CR!U87><

226

C & I E N T

A C C E S S

* I A

M M D A

A

:lGet!ITar=et

6e"nition=

 

6esc 6escrripti iption on==

%+%$:etI3ar'etFmm!Ctt %+%$:etI3ar'et Fmm!Ctt Vctt, mm!#ode VpiG 4ets 4ets the the tar targe gett for for this this pro proce cess ssin ing g inst instru ruct ctio ion. n.

 Argume  Arguments nts==

ctt ctt 3M/ parser parserpr proc ocess essor or sessio session n conte contet. t. pi #ode to get the processing instruction target from.

%eturns=

&onter to the processing instruction target on success. #// on fai!ure.

amp!e= include :mSmlliE.hG char *tar5et< tar5et = mSml2et/RVar5etctSt, pi>< if tar5et == 1U!!>  printf9ould not 5et tar5etn>< eSit7RV_;CR!U87>< A

:lGetTa=Nae

6e"nition= 6esc 6escrripti iption on==

 Argume  Arguments nts== %eturns=

 

%+%$:et3a'Na%eFmm!Ctt %+%$:et3a'Na%e Fmm!Ctt Vctt, mm!#ode VnodeG 4ets 4ets the the tag tag name name of this this e!em e!emen ent. t. his his is current!$ the same as the node name, but the 6OM -oring -oring 4roup considers it worthwhi!e to support both for now. ctt ctt node

3M/ parser parserpr proc ocess essor or sessio session n conte contet. t. #ode to get the name of.

&onter to the tag name on success. #// on fai!ure.

amp!e= include :mSmlliE.hG char *ta5name< ta5name = mSml2etVa51amectSt, node>< if ta5name == 1U!!>  printf9ould not 5et ta5namen>< eSit7RV_;CR!U87><

227

C & I E N T

A C C E S S

* I A

M M D A

A

:l)asC/ildNodes

6e"nition=

 

6esc 6escrripti iption on==

%+%$8asCi$dNodes Fmm!Ctt %+%$8asCi$dNodes  Fmm!Ctt Vctt, mm!#ode VnodeG 6ete 6eterm rmin ines es whe wheth ther er this this node node has has an$ an$ chi! chi!dr dren en..

 Argume  Arguments nts==

ctt ctt node

%eturns=

3M/ parser parserpr proc ocess essor or sessio session n conte contet. t. #ode to chec for chi!d nodes des.

1  he node has chi!d nodes. 0  he node does not ha(e chi!d nodes.

amp!e= include :mSmlliE.hG if mSmlJas9hild1odesctSt, node>>  printfVhis node has child nodesn>< eSit7RV_;CR!U87>< A

:lInsert%efore

6e"nition=

 

%+%$Insert6eforeFmm!Ctt %+%$Insert6efore Fmm!Ctt Vctt, mm!#ode Vparent, mm!#ode VnewChi!d, mm!#ode VrefChi!dG

6esc 6escrripti iption on==

Inse Insert rts s the the nod node e new newCh Chi! i!d d befo before re the the ei eist stin ing g node refChi!d. refChi!d. If refChi!d refChi!d is nu!!, inserts newChi!d at the end of the the !ist of chi!dren. chi!dren. If newChi!d is a document fragment, a!! of its chi!dren are inserted, in the same order, before refChi!d. If newChi!d is a!read$ a!read$ in the tree, tree, it is "rst remo(ed.

 Argume  Arguments nts==

ctt ctt 3M/ parser parserpr proc ocess essor or sessio session n conte contet. t. parent he re reference ch chi!d>s pa parent no node. newC newChi hi!d !d he he new new chi! chi!d d node node to inse insert rt.. refChi!d refChi!d he node node to to insert insert the the new node before.

%eturns=

&onter to the new chi!d node on success. #// on fai!ure.

amp!e= include :mSmlliE.hG mSml1ode *new9hild< new9hild = mSmlRnsertOeforectSt, parent, new, ref><

228

C & I E N T

A C C E S S

* I A

M M D A

if new9hild == 1U!!>  printf9ould not insert childn>< eSit7RV_;CR!U87>< A

:l!arse9ile F :l!arseStrin=

6e"nition=

 

%+%$arsei$eFmm!Ctt %+%$arsei$eFmm!Ctt Vctt, char VpathnameG %+%$arseStrin'Fmm!Ctt %+%$arseStrin' Fmm!Ctt Vctt, char Vm!G

6esc 6escrripti iption on==

&arse arse the the gi(e gi(en n 3M/ 3M/ docu docume ment nts str trin ing. g. his function !oads the contet for this parsing session.

 Argume  Arguments nts==

ctt ctt 3M/ parser parserpr proc ocess essor or sessio session n conte contet. t. path pathna name me &athn athname ame of the the 3M/ 3M/ docu docume ment nt.. m! 3M/ string to parse.

%eturns=

&onter to the document node on success. #// on fai!ure.

amp!e= include :mSmlliE.hG mSml1ode *document< document = mSml/arse;ilectSt, cPfoo.Sml>< if document == 1U!!>  printf9ould not parse D!n>< eSit7RV_;CR!U87>< A

:lReoveAttribute

6e"nition= 6escr escrip ipttion= ion=  Argume  Arguments nts==

%eturns=

 

%+%$Re%o,eAttri*)teFmm!Ctt %+%$Re%o,eAttri*)te Fmm!Ctt Vctt, mm!#ode Vnode, char VnameG %emo emo(es (es an att attribu ribute te b$ name name.. ctt ctt node node nam name

3M/ parser parserpr proc ocess essor or sessio session n conte contet. t. #ode to remo remo(e (e the the attri ttribu butte fro from. #ame ame of of the the att attribut ibute e to to rem remo o(e. (e.

eO\ on success. rror code on fai!ure.

amp!e= include :mSmlliE.hG lon5 status<

229

C & I E N T

A C C E S S

* I A

M M D A

status = mSml8emoveCttriEutectSt, node, units>< if status L= e">  printf9ould not remove attriEuten>< eSit7RV_;CR!U87>< A

:lReoveAttributeNode

6e"nition=

 

6escript iption=

%+%$Re%o,eAttri*)teNode Fmm!Ctt %+%$Re%o,eAttri*)teNode  Fmm!Ctt Vctt, mm!#ode Vnode, mm!#ode VattrG %emo(es (es an an at attribute no node.

 Argume  Arguments nts==

ctt ctt 3M/ parser parserpr proc ocess essor or sessio session n conte contet. t. node node #ode to remo remo(e (e the the attri ttribu butte node node from. attr Attribute node to remo(e.

%eturns=

eO\ on success. rror code on fai!ure.

amp!e= include :mSmlliE.hG lon5 status< status = mSml8emoveCttriEute1odectSt, node, attr>< if status L= e">  printf9ould not remove attriEute noden>< eSit7RV_;CR!U87>< A

:lReoveC/ild

6e"nition= 6esc 6escrripti iption on==  Argume  Arguments nts==

%eturns=

 

%+%$Re%o,eCi$dFmm!Ctt %+%$Re%o,eCi$d Fmm!Ctt Vctt, mm!#ode Vparent, mm!#ode Vchi!dG %emo %emo(e (es s the the chi! chi!d d nod node e chi chi!d !d from from the the !is !istt of of chi!dren ctt ctt 3M/ parser parserpr proc ocess essor or sessio session n conte contet. t. parent #ode to remo(e the chi!d node from. chi!d Chi!d node to remo(e. eO\ on success. rror code on fai!ure.

amp!e= include :mSmlliE.hG mSml1ode *old9hild<

230

C & I E N T

A C C E S S

* I A

M M D A

old9hild = mSml8emove9hildctSt, parent, child>< if old9hild == 1U!!>  printf9ould not remove childn>< eSit7RV_;CR!U87>< A

:lReoveNaedIte

6e"nition=

 

6esc 6escrripti iption on==

%+%$Re%o,eNa%edIte%Fmm!Ctt %+%$Re%o,eNa%edIte% Fmm!Ctt Vctt, mm!#ode/ist Vnode/ist, char VnameG %emo %emo(e (es s thi this s nam named ed node node from from this this node node !ist !ist..

 Argume  Arguments nts==

ctt ctt 3M/ parser parserpr proc ocess essor or sessio session n conte contet. t. node/ist #ode !ist to remo(e the node from. from. name #ame of th the node to remo(e. (e.

%eturns=

eO\ on success. rror code on fai!ure.

amp!e= include :mSmlliE.hG lon5 status< status = mSml8emove1amedRtemctSt, node!ist, name>< if status L= e">  printf9ould not remove noden>< eSit7RV_;CR!U87>< A

:lRepla0eC/ild

6e"nition=

 

%+%$Rep$aceCi$dFmm!Ctt %+%$Rep$aceCi$d Fmm!Ctt Vctt, mm!#ode Vparent, mm!#ode VnewChi!d, mm!#ode Vo!dChi!dG

6esc 6escrripti iption on==

%ep! %ep!ac aces es the the chi chi!d !d nod node e o!d o!dCh Chi! i!d d wit with h the the chi! chi!d d node newChi!d in the !ist of chi!dren. If newChi!d is a document fragment, o!dChi!d is rep!aced b$ a!! of the document fragment chi!dren, which are inserted in the the same order. order. If newChi!d is a!read$ in the tree, it is "rst remo(ed

 Argume  Arguments nts==

ctt ctt 3M/ parser parserpr proc ocess essor or sessio session n conte contet. t. pare arent &arent of the chi!d hi!d node to rep!ace. newChi!d #ew ch chi!d no node. o!dChi o!dChi!d !d O!d chi! chi!d d node. node.

231

C & I E N T

A C C E S S

%eturns=

* I A

M M D A

eO\ on success. rror code on fai!ure.

amp!e= include :mSmlliE.hG mSml1ode *old9hild< old9hild = mSml8eplace9hildctSt, parent, new, old>< if old9hild == 1U!!>  printf9ould not replace childn>< eSit7RV_;CR!U87>< A

:lSetAttribute

6e"nition=

 

6esc 6escrripti iption on==

Fmm!Ctt Vctt, mm!#ode %+%$SetAttri*)teFmm!Ctt %+%$SetAttri*)te Vnode, char Vname, char V(a!ueG Adds Adds a new new attr attrib ibut ute. e. If an attr attrib ibut ute e wit with h tha thatt name is a!read$ present in the e!ement, its  (a!ue  (a!ue is is chan changed ged to be that that of of the the (a!u (a!ue e parameter.

 Argume  Arguments nts==

ctt ctt node nam name  (a!ue  (a!ue

%eturns=

3M/ parser parserpr proc ocess essor or sessio session n conte contet. t. #ode to to se set th the at attribute in in. #ame ame of the att attribut ibute e to set. set. *a!ue a!ue of of the the attrib attribute ute to set. set.

eO\ on success. rror code on fai!ure.

amp!e= include :mSmlliE.hG lon5 status< status = mSml0etCttriEutectSt, node, units, lEs>< if status L= e">  printf9ould not set attriEute valuen>< eSit7RV_;CR!U87>< A

:lSetAttributeNode

6e"nition= 6esc 6escrripti iption on==

 

%+%$SetAttri*)teNodeFmm!Ctt %+%$SetAttri*)teNode Fmm!Ctt Vctt, mm!#ode Vnode, mm!#ode VattrG Adds Adds a new new attr attrib ibut ute e nod node. e. If an attr attrib ibut ute e wit with h that name is a!read$ present in the e!ement, it is rep!aced with the new one.

232

C & I E N T

A C C E S S

 Argume  Arguments nts==

* I A

M M D A

ctt ctt node attr

%eturns=

3M/ parser parserpr proc ocess essor or sessio session n conte contet. t. #ode to se set th the at attribut bute no node in in. Attribute node to add.

eO\ on success. rror code on fai!ure.

amp!e= include :mSmlliE.hG lon5 status< status = mSml0etCttriEute1odectSt, node, attr>< if status L= e">  printf9ould not set attriEute noden>< eSit7RV_;CR!U87>< A

:lSetAttr*alue

6e"nition=

 

6esc 6escrripti iption on==

%+%$SetAttrVa$)eFmm!Ctt %+%$SetAttrVa$)e Fmm!Ctt Vctt, mm!#ode Vattr, char V(a!ueG )ets )ets the the (a!u (a!ue e of the the gi(e gi(en n attr attrib ibut ute. e.

 Argume  Arguments nts==

ctt ctt attr  (a!ue  (a!ue

%eturns=

3M/ parser parserpr proc ocess essor or sessio session n conte contet. t. Attribute no node to set the (a!ue of. Attri Attribut bute e (a!ue (a!ue to set. set.

eO\ on success. rror code on fai!ure.

amp!e= include :mSmlliE.hG lon5 status< specd = mSml0etCttrWaluectSt, attr, my value>< if status L= e">  printf9ould not set attriEute valuen>< eSit7RV_;CR!U87><

:lSetC/ara0terData

6e"nition= 6esc 6escrripti iption on==

 

Fmm!Ctt Vctt, %+%$SetCaracter4ataFmm!Ctt %+%$SetCaracter4ata mm!#ode Vnode, char VdataG )ets )ets the the cha chara ract cter er data data for for thi this s C6A C6AA for for tet tet node.

233

C & I E N T

A C C E S S

 Argume  Arguments nts==

* I A

ctt ctt node node data

%eturns=

M M D A

3M/ parser parserpr proc ocess essor or sessio session n conte contet. t. #ode to set set the the char haract acter data ata of of. Character data to set.

eO\ on success. rror code on fai!ure.

amp!e= include :mSmlliE.hG lon5 status< status = mSml0et9haracter#atadctSt, node, my data>< if status L= e">  printf9ould not set character datan>< eSit7RV_;CR!U87>< A

:lSetNaedIte

6e"nition=

 

6escr escrip ipttion= ion=

%+%$SetNa%edIte%Fmm!Ctt %+%$SetNa%edIte% Fmm!Ctt Vctt, mm!#ode/ist Vnode/ist, mm!#ode VnodeG Adds dds this this node node to this this node node !ist !ist..

 Argume  Arguments nts==

ctt ctt 3M/ parser parserpr proc ocess essor or sessio session n conte contet. t. node/ist node/ist #ode !ist to add the the node to. node #ode to add to to th the no node !i !ist.

%eturns=

eO\ on success. rror code on fai!ure.

amp!e= include :mSmlliE.hG lon5 status< status = mSml0et1amedRtemctSt, node!ist, node>< if status L= e">  printf9ould not add noden>< eSit7RV_;CR!U87>< A

:lSetNode*alue

6e"nition= 6escript iption=  Argume  Arguments nts==

 

%+%$SetNodeVa$)eFmm!Ctt %+%$SetNodeVa$)e Fmm!Ctt Vctt, mm!#ode Vnode, char V(a!ueG )ets th the (a (a!ue !ue of of th this node. ctt ctt node  (a!ue  (a!ue

3M/ parser parserpr proc ocess essor or sessio session n conte contet. t. #ode to set the (a!ue of. *a!ue a!ue to to set set the node node to to.

234

C & I E N T

A C C E S S

* I A

%eturns=

M M D A

eO\ on success. rror code on fai!ure.

amp!e= include :mSmlliE.hG lon5 status< status = mSml0et1odeWaluectSt, node, my value>< if status L= e">  printf9ould not set node valuen>< eSit7RV_;CR!U87>< A

:lSet!IData

6e"nition=

 

6esc 6escrripti iption on==

%+%$SetI4ataFmm!Ctt %+%$SetI4ataFmm!Ctt Vctt, mm!#ode Vpi, char VdataG )ets )ets the the dat data a for for this this pro proce cess ssin ing g ins instr truc ucti tion on

 Argume  Arguments nts==

ctt ctt 3M/ parser parserpr proc ocess essor or sessio session n conte contet. t. pi &rocessing instruction to set the data of. data 6ata to set in the processing instruction.

%eturns=

eO\ on success. rror code on fai!ure.

amp!e= include :mSmlliE.hG lon5 status< status = mSml0et/R#atactSt, pi, version=.%>< if status L= e">  printf9ould not set datan>< eSit7RV_;CR!U87>< A

:lStart!arser 

6e"nition= 6esc 6escrripti iption on==

 

%+%$Startarser Fmm!Ctt Fmm!Ctt VVcttG )tar )tartt a new new docu docume ment nt pars parsin ing g sess sessio ion. n. his function must be ca!!ed once for each 3M/ document and must be ca!!ed before ca!!ing an$ other functions within mm!!ib.

 Argume  Arguments nts==

ctt ctt

3M/ parser parserpr proc ocess essor or sessio session n conte contet. t.

235

C & I E N T

A C C E S S

%eturns=

* I A

M M D A

eO\ on success. rror code on fai!ure.

amp!e= include :mSmlliE.hG mSml9tSt *ctSt = 1U!!< if mSml0tart/arser?ctSt> L= e">  printf9ould not start parsin5 sessionn>< eSit7RV_;CR!U87>< A

:lStop!arser 

6e"nition=

 

6esc 6escrripti iption on==

%+%$Stoparser Fmm!Ctt Fmm!Ctt VcttG )top )tops s an eis eisti ting ng 3M/ 3M/ pars parsin ing g sess sessio ion. n. his function must be ca!!ed once after parsing an 3M/ document in order to rec!aim resources associated with the parsing session.

 Argume  Arguments nts==

ctt ctt

%eturns=

3M/ parser parserpr proc ocess essor or sessio session n conte contet. t.

(oid

amp!e= include :mSmlliE.hG mSml9tSt *ctSt = 1U!!< mSml0tart/arser?ctSt>< mSml0top/arserctSt><

:lStrin= F :lRa8Strin=

6e"nition=

 

%+%$Strin'Fmm!Ctt %+%$Strin'Fmm!Ctt Vctt, mm!#ode VnodeG %+%$RawStrin'Fmm!Ctt %+%$RawStrin'Fmm!Ctt Vctt, mm!#ode VnodeG

6esc 6escrripti iption on==

4et 4et the the seri seria! a!iX iXed ed 3M/ 3M/ for for the the gi( gi(en en pars parsin ing g session, starting at node. node. If node is node is #//, get the seria!iXed string for the entire 3M/ document. %+%$RawStrin' returns %+%$RawStrin' returns entit$ references for the fo!!owing s$mbo!s= Z T  J ?.

 Argume  Arguments nts==

ctt ctt node

3M/ parser parserpr proc ocess essor or sessio session n conte contet. t. )tarting node to seria! ia!iXe.

236

C & I E N T

A C C E S S

%eturns=

* I A

M M D A

&onter to the seria!iXed 3M/ on success. #// on fai!ure.

amp!e= include :mSmlliE.hG char *Sml< Sml = mSml0trin5ctSt, 1U!!><

:lrite9ile F :lRa8rite9ile

6e"nition=

 

%+%$>ritei$eFmm!Ctt %+%$>ritei$eFmm!Ctt Vctt, mm!#ode Vnode, char VpathnameG %+%$Raw>ritei$e Fmm!Ctt Vctt, %+%$Raw>ritei$eFmm!Ctt mm!#ode Vnode, char VpathnameG

6esc 6escrripti iption on==

-rite rite the the ser seria ia!i !iXe Xed d 3M/ 3M/ for for the the gi( gi(en en pars parsin ing g session, starting at node, node, to the gi(en "!e. "!e. If node is node is #//, write the seria!iXed 3M/ for the entire 3M/ document. %+%$Raw>ritei$e  writes entit$ references %+%$Raw>ritei$e writes for the fo!!owing s$mbo!s= Z T  J ?.

 Argume  Arguments nts==

%eturns=

ctt ctt 3M/ parser parserpr proc ocess essor or sessio session n conte contet. t. node )tarting node to seria! ia!iXe. path pathna name me &athn athname ame of "!e "!e to to wri write te.. eO\ on success. rror code on fai!ure.

amp!e= include :mSmlliE.hG if mSml`rite;ilectSt, 1U!!, cPfoo.Sml> L= e">  printf9ould not write filen>< eSit7RV_;CR!U87>< A

237

C & I E N T

A C C E S S

* I A

M M D A

MOCA COM A00ess C/apter 

 Ac  Accessin+ MOCA rom Fisual 4asic or ava throu+h COM!

'

= B9ol1ameFs WalueB

-hereas in *isua! SS Fusing SSLs COM wrappers and M)Ls COM support c!assesG res.setWaluenew WariantB9ol1ameB>, new WariantB9olWalueB><

Other !anguages wi!! ha(e their own COM interface Buirs, most of whic which h are are we!! we!! docu docume ment nted ed b$ the the de(e de(e!!opme opment nt too too! manufacturer, and man$ too!s ha(e a COM object browser that wi!! wi!! tran trans! s!at ate e MOCA MOCALs Ls obje object ct de"n de"nit itio ion n into into s$nt s$nta a that that is comfortab!e for that !anguage.

238

C & I E N T

A C C E S S

* I A

M M D A

T/e MOCA Server Ob2e0ts &ibrar7  A!! the MOCA MOCA suppor supportt object objects s are imp!emen imp!emented ted in the COM in' process ser(er MOCA)r(Obj.d!!, which is usua!!$ insta!!ed with the the rest rest of the the MOCA MOCA ser( ser(er er's 'sid ide e inst insta! a!!a !ati tion on.. Once Once itLs itLs regis register tered, ed, it wi!! show show up in most most COM'aw COM'aware are de(e!o de(e!opme pment nt en(ironments, such as *isua! +asic or Microsoft SS, as a!! other COM objects do. FIn *isua! +asicG

FIn Microsoft SSG

239

C & I E N T

A C C E S S

* I A

M M D A

T/e MOCADat MOCADataT7pes aT7pes Enueration he MOCA6ata$pes enumeration is a !isting of (a!id data t$pes to be used used b$ (arious methods of the MOCA%esu!ts object. ach  (a!ue  (a!ue corres correspon ponds ds to a (a!id (a!id COMW& COMW&H H (a!ue (a!ue as used used within within MOCA and C'based MOCA components.

*alues MOCAInt

COMW&HI#

Integer

MOCAStrin'

COMW&H)%I#4

MOCA$oat

COMW&H
)tring
MOCA6oo$ean COMW&H+OO COMW&H+OO/A# /A# +oo!ean +oo!ean MOCA4ate3i%e

COMW&H6AIM

MOCARes)$ts COMW&H%)/)

%esu!ts

MOCA6inar&  COM&W&H+I#A%W

+inar$

240

6ateime

C & I E N T

A C C E S S

* I A

M M D A

T/e MOCAErrors Enueration he MOCArrors enumeration is a !isting of common erorr codes coming coming from MOCA and the database database.. O(er time, time, the (a!ues in this his enum enumer erat atio ion n wi!! wi!! chang hange, e, rePe ePectin cting g chang hanges es to the under!$ing MOCA structure. A!so, components components can return their their own error error codes. codes.
*alues rror )$mbo!

*a!u e

Meaning

eO\

0

#o rror ' )uccess

e%%O%

2

4enera! MOCA error. Often returned from commands and functions that are not epected to get errors.

e#OHMMO%W

7

he MOCA )er(er ran out of   memor$ during a!!ocation.

e)%*HI#*A/I6HCOMMA  #6

701

An in(a! (a!id co command wa was se sent to MOCA.

e)%*H&A%)H%%O%

707

A bad!$'formed command was sent to MOCA.

e)%*H#OH%O-)HA<<C 6

710

A Bue Buer$ cam came ba bac wit with no rows. Fhis is not usua!!$ seen from within ser(er comm comman ands ds.. he$ he$ get get the the actua! database error Fe6+H#OH%O-)HA<<C6G

e)%*H6+H%%O%

711

A co command ca came ba bac wi with an unepected databa abase erro errorr. Fhi Fhis s is not not usua! usua!!$ !$ seen from within ser(er comm comman ands ds.. he$ he$ get get the the

241

C & I E N T

A C C E S S

* I A

M M D A

Fe6+HVG e6+H#OH%O-)HA<<C 6

' 1]0 8

 A Buer$ Buer$ came came bac bac norma!, norma!, but with no rows.

e6+H6A6/OC\

':0

A Buer$ or update dead!oced, and this processthread was chosen to die.

e6+H#IHCO#)H*IO

'1

An updateinsert was unab!e to comp!ete due to a constraint (io!ation or dup!icate uniBue inde.

here are other errors that cou!d be returned, but these are the most common ones.

T/e MOCARe MOCAResults sults Ob2e0t he "rst object to now is the  MOCARe  MOCAResul sults ts object object FCOM Interface  IMOCAR  IMOCAResu esults ltsGG. Objects of t$pe  MOCARe  MOCAResul sults ts represent the MOCA resu!t structures that are represented b$ moca moca6a 6ata ta%e %es, s, moca moca6a 6ata ta%o %ow w and and % %%# %#H) H)% %C C  for for C components. Most COM'based COM'based MOCA components components wi!! return return a MOCA%esu!ts object as their output.

!roperties &ropert$ Rows &ropert$  Rows As  As /ong Fread on!$G %eads the number of rows in the resu!t set. &ropert$ Co$)%ns &ropert$  Co$)%ns As  As /ong Fread on!$G %eads the number of co!umns in the resu!t set. &ropert$ Co$Na%e &ropert$  Co$Na%eFFCol2um as Col2um as /ongG As /ongG  As )tring Fread on!$G %eturns the co!umn name of the co!umn in position Col2um in Col2um in the the resu!t set. If the resu!t set is in(a!id, or there is no co!umn numbered Col2um, Col2um, an empt$ string is returned. &ropert$ Co$N)% &ropert$  Co$N)%FFCol2ame as Col2ame as )tringG As )tringG  As /ong Fread on!$G %eturns the co!umn number of the co!umn named Col2ame in Col2ame in the resu!t set. If the resu!t

242

C & I E N T

A C C E S S

* I A

M M D A

set is in(a!id, or the co!umn does not eist, '1 is returned.  !*AData+ a+ypes ypes &ropert$ 4ata3&peF 4ata3&peF Inde*  Inde* as  as *ariantG As !*ADat Fread on!$G %eads the data t$pe of of a co!umn. he co!umn can be referred to b$ positionFXero'basedG p ositionFXero'basedG or b$ name, so it is indeed b$ the *ariant Ind ariant Inde* e*.. he  (a!ue  (a!ue of of the the 6ata 6ata$p $pe e pro proper pert$ t$ is one one of the enumerated t$pes in the MOCA6ata$pes enumeration.

&ropert$ EO As EO As /ong Fread on!$G rue when the resu!t set is at the end of its !ist of rows. -hen this is true, no more more data can can be fetched from the resu!ts. &ropert$ Stat)s as Stat)s as /ong )ets or %eads the numeric status of the associated )/ statement or MOCA command. Yero F0G is considered norma! Faa eO\G. &ropert$ V &ropert$ Va$) a$)e eF Inde*  Inde* as  as *ariantG as *ariant )et or read the (a!ue of a co!umn in the current row. he co!umn can be referred to b$ position FXero'basedG or b$ name, so it is indeed b$ the  *ari  *ariant ant Ind  Inde* e*.. he (a!ue of the co!umn can a!so be an$ data t$pe, so it is a!wa$s returned as a  *ari  *ariant ant.. &ropert$ 4e/neden'tF 4e/neden't F Inde*  Inde* as  as *ariantG As !ong Fread on!$G %eads the maimum de"ned !egnth of a co!umn. he co!umn can be referred to b$ positionFXero' basedG or b$ name, so it is indeed b$ the  *ari  *ariant ant Ind  Inde* e*..

Met/ods )ub Add )ub AddCo Co$)% $)%n nFColumn2ame As Column2ame As )tring, Bat )tring, BataTyp aType e As  !*AData  !*AData+ +ypes ypesG  Adds  Adds a co!um co!umn n to the curren currentt resu resu!t !t set. set. his his  !*A,esults lts can on!$ be done on a new !*A,esu object before being opened, or on one that has been c!osed. c!osed. After opening, the co!umn de"nition is "ed. )ub Add )ub AddCo Column2ame As )tring, Bat )tring, BataTyp aType e As Co$)% $)%n2 n2FFColumn2ame As  !*AData  !*AData+ +ypes$ ypes$ ColumnLen+th As Lon+ G

243

C & I E N T

A C C E S S

* I A

M M D A

 Adds  Adds a co!um co!umn n to the curren currentt resu resu!t !t set, set, using using the Co!umn/ength as the maimum de"ned !ength of the gi(en co!umn if the co!umn is of  !*AString ing. his can on!$ t$pe !*AStr on!$ be done done on a  !*A,esults lts object before being new !*A,esu opened, or on one that has been c!osed. c!osed. After opening, the co!umn de"nition is "ed. )ub Add )ub AddErr  2ame As )tring, Falue As Falue As *ariant, Error orAr' Ar'FF 2ame  BoLoo  BoLoo(up (up As  As /ongNG  Adds  Adds an an err error or argume argument, nt, for a para paramet meteri eriXed Xed error message, of the sort used b$ sr(rror%esu!tsFG. sr(rror%esu !tsFG. o set the status andor defau!t error tet, see the Open method. Open method. )ub Add )ub AddRow  Row FG FG  A!!ocat  A!!ocates es a new new row row to to the the resu! resu!tt set. set. )ub Mo,eirstFG Mo,eirstFG Mo(es the current row pointer to the "rst row. his is usefu! for UrewindingU a resu!t set for !ater perusa!. )ub Mo,eNe+tFG Mo,eNe+t FG Mo(es the current row pointer to the net row. row. his a!!ows a component to step through the resu!ts, row b$ row, row, !ooing at (a!ues. sub OpenF OpenFStatus Status as /ongN,  Beaul  BeaultT tTe*t e*t as )tringNG
244

C & I E N T

A C C E S S

* I A

M M D A

T/e MOCAServerA00ess Ob2e0t he he othe otherr obje object ct in the the MOCA MOCA )er( )er(er er Obje Object cts s !ibr !ibrar ar$ $ is the the MOCA)e MOCA)er(e r(erAc rAcces cess s object object.. his his a!!ows a!!ows COM access access to most most MOCA ser(er A&I functiona!it$.

!roperties #one

Met/ods
245

C & I E N T

A C C E S S

* I A

M M D A

searched to "nd the most recent instance of a  (ariab  (ariab!e !e with with the name name cont containe ained d in either either name> or name> or name?. name?. If the (ariab!e is not found, #// is returned. arnin'F o'>arnin'F Messa+  Messa+e e As )tringG )ub o'InfoF o'InfoF Messa+  Messa+e e As )tringG )ub o'Error F Messa+  Messa+e e As )tringG /og error, error, warning or informationa! messages. he Message in Mes in Messa+ sa+e e is !ogged to the app!ication e(ent !og as an error, error, warning or informationa! message, depending on which ca!! is made. )ince the app!ication e(ent !og is a !imited s$stem resource, these ca!!s shou!d not be used for debug informatin, but rather for usefu! messages that aect the s$stem and shou!d be !ogged.

%uildin= a COM6based MOCA 0oponent he wa$ that MOCA interfaces into COM is (ia the I6ispatch interf interface ace.. I6ispat I6ispatch ch a!!ows a!!ows us to "nd "nd the object object at run'ti run'time, me, rather rather than ha(ing ha(ing to now about about it at compi!e compi!e time. It>s often often referred to b$ the terms ?automation support@, ?!ate binding@ or

246

C & I E N T

A C C E S S

* I A

M M D A

some someth thin ing g simi simi!a !arr. he he meth method od we ca!! ca!! shou shou!d !d retu return rn a  !*A,e  !*A,esult sults s object,  object, or a status status Fin a !ongG. !ongG. Components Components are are de"ned (ia the same con"guration "!es as for C components. he on!$ dierence is the addition of the ?&rogram'Id@ "e!d in the Component'!e(e!F.m!(!G "!e, and changing the ?$pe@ "e!d to ?COM@ in the mcmd "!e. NO3E NO3E 3e pro'ra pro'ra%-i %-id d was %o,ed %o,ed fro% te te co%%and co%%and /$eO*Dect /$eO*Dect ta'! to te co%ponent $e,e$ /$epro'ra%-id ta'! to 'i,e COM s)pport to te MOCAInitia$iBe MOCAVersion and MOCA$icense %etods. 3erefore COM co%ponents co%ponents %a& %a& a,e 1 AN4 AN4 ONF ONF 1 inter interfac face. e. 3is 3is interfac interface e %a&  a,e as %an& %etods as needed. he wa$ MOCA in(o in(o es the de"ned method sho shou!d be considere considered d as we!!. MOCA creates creates an object object with with the &rogI6 &rogI6 speci"ed in the component !e(e! de"nitionF&rogram'IdG, ca!!s the meth metho od spec peci"e i"ed in the the compo ompone nent nt de" de"nitio ition, n, and and then hen object is etr etreme eme!$ !$ immedi immediate ately ly destro destroys ys the ob-ect ob-ect. he object short'!i(ed, and to p!a$ we!! with MOCA, shou!d not tr$ to eep state within itse!f.  SS  SS am amp!e p!e QereLs a a(a c!ass that that imp!ements a MOCA command. Most of  the strange!$ formatted comments were put in b$ the SS c!ass wiXard, and FI assumeG are necessar$ to imp!ement a COM c!ass in SS. 31  1 his class is desi$ned to be packa$ed with a COM 7## output format%  1 he class has no standard entry points, other than the constructor%  1 ublic methods will be e(posed as methods on the default COM interface%  1 2com%re$ister  clsid7>)))K>:6C=+L6))7L6=K+96:::;CK<=AC>K, typelib7>)))K>)6C=+L6))7L6=K+96:::;CK<=AC>K   13 import mocasrvob%1H import com%ms%com%GariantH 31  1 2com%re$ister clsid7>)))K*<6C=+L6))7L6=K+96:::;CK<=AC>K, 1 typelib7>)))K*L6C=+L6))7L6=K+96:::;CK<=AC>K   13 33 his is a sample MOCA server6side component written in M& Gisual 33 DD *%:% It is implemented by a COM obect% he prototypical 33 MOCA component will return a MOCA?esults, and take any number 33 of &trin$, Inte$er, or 9loat parameters% 33 33 &le component level file 33 Component6#evel MOCACOM 33 7escription MOCA Com est

247

C & I E N T

A C C E S S

* I A

M M D A

33 &ort6&ePuence : 33 #ibrary6Name MOCACom 33 ro$ram6Id est%Class) 33 7irectory mocacom 33 4nd6Component6#evel 33 Command test ava 33 #evel MOCACOM 33 &tatement6.ualifier Optional 33 Insecure N 33 ype COM 33 9unction 7ohin$ 33 Ar$ument &trin$ param)param@one ?ePuired 33 Ar$ument &trin$ stolocstora$e@location 33 4nd6Command public class Class)  private static MOCA&erverAccess moca  new MOCA&erverAccessH 31 1 NO4 o add auto6re$istration code, refer to the documentation 1 on the followin$ method 1 public static void onCOM?e$isterboolean un?e$ister F 13 public IMOCA?esults 7ohin$&trin$ param)  IMOCA?esults out?esH IMOCA?esults sPl?esH 33 Initiate a command to fill out result set moca%race9low"About to 4(ecute &tatement"H sPl?es  moca%Initiate"select '" Dparam)D"' column), 'estin$' column+ from dual-"H 33 Create a new result set for return% out?es  new MOCA?esultsH 33 Add two columns, both of type strin$ out?es%AddColumn"col)", MOCA7ataypes%MOCA&trin$H out?es%AddColumn"col+", MOCA7ataypes%MOCA&trin$H 33 InitialiQe the result set% out?es%OpensPl?es%$et&tatus, ""H 33 Add a row with constant3parameter data out?es%Add?owH out?es%setGaluenew Gariant"col)", new Gariantparam)H out?es%setGaluenew Gariant"col+", new Gariant"this is column +"H

 

33 Add a row with data derived from an e(ecuted statement% out?es%Add?owH out?es%setGaluenew Gariant"col)", sPl?es%$etGaluenew Gariant"column)"H out?es%setGaluenew Gariant"col+", sPl?es%$etGaluenew Gariant"column+"H

 

moca%race9low"7one with command"H

F

F

return out?esH

248

C & I E N T

A C C E S S

* I A

M M D A

 A simi!a simi!arr c!ass c!ass,, writt written en in in *isua *isua!! +asic +asic,, might might !oo !oo someth something ing !ie !ie this. 7im moca As MOCA&erverAccess ' ' ' ' ' R R R R R R R R

his is a sample MOCA server6side component written in Gisual 8asic *%:% It is implemented by a COM obect% he prototypical MOCA component will return a MOCA?esults, and take any number of &trin$, Inte$er, or 9loat parameters% &le component level file Component6#evel MOCACOM 7escription MOCA Com est &ort6&ePuence : #ibrary6Name MOCACom ro$ram6Id G8est%G8Class) 7irectory mocacom 4nd6Component6#evel

' Command test com ' #evel MOCACOM ' &tatement6.ualifier Optional ' Insecure N ' ype COM ' 9unction 7ohin$ ' Ar$ument &trin$ lodnumload@num ?ePuired ' Ar$ument &trin$ stolocstora$e@location ' 4nd6Command ublic 9unction 7ohin$lodnum As &trin$, Optional stoloc As &trin$ As MOCA?esults 7im results As MOCA?esults 7im foobar As &trin$ 7im i As #on$

@

' 4(ecute a &.# statement &et results  moca%&.#4(ecute"select '" S lodnum S "' lodnum, " S

dual"

"'" S stoloc S "' stoloc, L%)<)>= pi from

' Create a new result set% &et 7ohin$  New MOCA?esults ' 7efine the Columns to be stored in the result set 7ohin$%AddColumn "testin$", MOCA&trin$ 7ohin$%AddColumn "test+", MOCAInt ' Open the result set% his must be done before we can add a row% 7ohin$%Open results%status  

 

 

' Add a row with constants 7ohin$%Add?ow 7ohin$%Galue"testin$"  "?ow@:%Column@:" 7ohin$%Galue"test+"  =::+ ' Add a row with results from the previous Puery 7ohin$%Add?ow 7ohin$%Galue"testin$"  results%Galue: 7ohin$%Galue"test+"  results%Galue+ ' Add a row with elements from the current MOCA conte(t% 7ohin$%Add?ow 7ohin$%Galue"testin$"  moca%BetNeeded4lement"foobar" 7ohin$%Galue"test+"  moca%BetNeeded4lement"i"

249

C & I E N T

A C C E S S

* I A

M M D A

moca%race9low "Added three rows%%%they're comin$ back" 4nd 9unction rivate &ub Class@InitialiQe &et moca  New MOCA&erverAccess moca%race9low "InitialiQin$ Class Obect G8Class)" 4nd &ub rivate &ub Class@erminate moca%race9low "erminatin$ Class Obect G8Class)" &et moca  Nothin$ 4nd &ub

)ince the MOCA )er(er Object !ibrar$ hand!es much of the wor  of interfacing with other parts of MOCA, the major dierences betw betwee een n the the two two eam eamp! p!es es abo(e abo(e is s$nt s$nta a.. *+, *+, bein being g a comp!ete!$ Microsoft creation, is stream!ined to dea! with COM objects. a(a, For rather rather SS '' it>s not actua!!$ a(aG, ha(ing a s$nta and some semantics contro!!ed b$ eterna! entities, must adhere to those standards, and transparent COM support is not Buite as nice. nice. ither wa$, though, the dieren dierences ces are most!$ most!$ cosmetic with regard to COM, so the !anguages can be e(a!uated on their own merits, and the choice of too!s can be!ong with the de(e!oper.

250

C & I E N T

A C C E S S

* I A

M M D A

Usin= MOCA fro *isual %asi0

Client A00ess via MMDA

This chapter provides descriptions o the  MMBA  MMBA COM COM o#ec o#ectt and and ho& to use it to ena#le Dindo&sJ client access!!

C/apter 



Much of the MOCA !ibrar$ structure introduced so far is from the pers perspe pect cti( i(e e of a MOCA OCA comp compon onen entt writ ritten ten in the the C prog progra ramm mmin ing g !angu !anguag age. e. Man$ Man$ of the the MOCA MOCA A&I ca!!s ca!!s are necessar$ to imp!ement a MOCA component in C, but become Buite Buite cumber cumbersom some e when when imp!em imp!ement enting ing a c!ient c!ient in Micro Microsof softt  *isua  *isua!! +asic or or a simi!ar simi!ar too!. too!. Ca!!ing Ca!!ing a C functi function on from from another another !ang !angua uage ge can can be tedi tediou ous s at best best,, and Ffor Ffor some some !ang !angua uage gesG sG impossib!e at worst. worst. Microsoft has has addressed this issue with the Compon Component ent Object Object Mode!, Mode!, or COM framewo framewor. r. -ithin -ithin that framewo framewor, r, Micros Microsoft oft has creat created ed the Acti(e Acti(e3 3 6ata 6ata Object Objects s c!asses, or A6O. A6O. MM6A uti!iXes the A6O %ecordset objects objects and a!!ows MOCA command resu!ts to "!! an A6O %ecordset object.

ADO Re0ordset Overvie8  A %ecord %ecordset set obje object ct encap encapsu! su!ate ates s the entir entire e set of reco records rds from from a base tab!e or the resu!ts of an eecuted command. At an$ time, the %ecordset object refers to on!$ a sing!e record within the set as the curre current nt recor record. d. In MOCA MOCA termin termino!o o!og$ g$,, the %ecor %ecordse dsett object wou!d contain a!! of the data returned from the MOCA  ser(e ser(err. A!! %ecor %ecordse dsett object objects s are constr construct ucted ed using using recor records ds FrowsG and "e!ds Fco!umnsG. he MOCA C!ient 6ata Access Component maes etensi(e use of disconnected recordsets.

Dis0onne0ted Re0ordsets  A disconn disconnect ected ed recor recordse dsett is one of of the power powerfu! fu! featu feature res s of A6O wherein the connection is remo(ed from a popu!ated recordset. his his recor recordse dsett can be manipu! manipu!ate ated d b$ the c!ient c!ient app!ic app!icati ation, on, bound to data contro!s, rows can be updated, added or de!eted, and then used to bui!d commands for the MOCA ser(er. ser(er.  A disco disconne nnecte cted d recor recordse dsett can be progra programma mmatic tica!! a!!$ $ creat created ed without the use of the %6) )er(er framewor or an$ c!ient side components. One of the primar$ reBuisites for a recordset to become a disconnected recordset is that it shou!d use c!ient side cursor cursors. s. hat hat is, the Cursor Cursor/oc /ocatio ation n shou!d shou!d be initia! initia!iXe iXed d to LadseC!ientL. In *isua! +asic, disconnecting a recordset can be done b$ setting the Acti(eConnection propert$ to L#othingL. -ith CSS and a(a, $ou wou!d accomp!ish the same thing b$ setting the Acti(eConnection to #//.  Anothe  Anotherr featur feature e of a discon disconnec nected ted recor recordse dsett is that that pendin pending g oper operat atio ions ns can can be Ucom Ucommi mitt tted edUU to the the reco record rdse set. t. An$ An$ time time pdate+atch is ca!!ed on a c!ient cursor that has no  Acti(e  Acti(eCon Connec nectio tion n set, set, the the chan changes ges in the the aect aected ed row row Fcontr Fcontro!! o!!ed ed b$ the A the Aect ectedR edRo&s o&s parameterG  parameterG wi!! be committed to the buer and the )tatu atus Pags wi!! be reset. he he same app!i pp!ie es to Cance!+atch, ecept the changes in the buer wi!! be re(erted and the Pag wi!! be reset. his pro(ides a (er$ rich c!ient side programming mode!.

Re0ordset !ersisten0e  A side side bene" bene"tt of support supporting ing A6O recor recordse dsets ts is that that a record recordset set can be persisted. A6O has added support for doing this b$ gi(ing the de(e!oper the abi!it$ to sa(e a c!ient cursor recordset to dis  and re!oad it !ater. his cou!d be (er$ (a!uab!e to a c!ient side de(e!oper for performing !oca! data (a!idation and !ooups.
MOCA Data A00ess Coponent he MOCA 6ata Access component For MM6AG is a COM based, non'(isua! component. he MM6A pro(ides !ow'!e(e! data access

252

to the MOCA ser(er ser(er engine. he MM6A )er(er )er(er is imp!emented as a COM in'process ser(er.

DataA00ess Ob2e0t he he 6ata 6ataAc Acce cess ss obje object ct is the the obje object ct that that is inst instan anti tiat ated ed b$ c!ie c!ient nts. s. It enca encaps psu! u!at ates es the the !ow' !ow'!e !e(e (e!! MOCA MOCA data data acce access ss.. It imp!em imp!ement ents s the custom custom I6ataA I6ataAcce ccess ss interf interface ace.. he fo!!ow fo!!owing ing tab! tab!e e show shows s the the spec speci" i"c c attr attrib ibut utes es or char charac acti tist stic ics s of the the 6ataAccess object. Characteristic

*a!ue

Object #ame

6ataAccess

C!ass #ame

C6ataAccess

CoC!ass

6ataAccess

Interface

I6ataAccess

$pe

MOCA 6ata Access C!ass

&rogI6

MM6A.6ataAccess

hreading Mo Mode!

Apartment

 Automa  Automatio tion n )upport

 W)

 Aggrega  Aggregatio tion n )upport

 W)

Comments

#ame of c!ass imp!ementing the I6ataAccess interface.

#ame of interface eposed b$ object. his interface wi!! be the c!ientLs on!$ access to the object.

&rogI6 used b$ c!ients to create an instance of the object.

IsupportrrorInfo

W)

&ro(ides support for the  Automat  Automation ion IrrorI IrrorInfo nfo interface. his interface pro(ides c!ients with rich error hand!ing information.

Connection &oint )upport

#O

#ot reBuired at this time.


#O

#ot reBuired at this time.

253

Marsha!!er

!roperties )ostNae !ropert7 @MMDA

6esc 6escrripti iption on==

)pec )peci" i"es es the the hos hostt nam name e of of the the MOCA MOCA ser( ser(er er to which the c!ient is current!$ connected to

%eturns=

A 6S3R  (a!ue.  (a!ue.

%emars=

A read'on 'on!$ propert$ that indic ndica ates the I& host name of the MOCA ser(er. ser(er. On!$ (a!id when the c!ient app!ication is connected to the MOCA ser(er. ser(er. If the c!ient is not connected, this propert$ (a!ue wi!! be set to a #// string.

#ote=

his propert$ can on!$ be set with the Initia!iXe method.

!ortNuber !ropert7 @MMDA

6esc 6escrripti iption on==

)pec )peci" i"es es the the por portt num numbe berr of of the the MOCA MOCA ser ser(er (er to which the c!ient is current!$ connected to

%eturns=

A sort (a!ue. sort (a!ue.

%emars=

A read'on 'on!$ propert$ that indic ndica ates the I& port number name of the MOCA ser(er. ser(er. On!$ (a!id when the c!ient app!ication is connected to the MOCA ser(er. ser(er. If the c!ient is not connected, this propert$ (a!ue wi!! be set to '1.

#ote=

his propert$ can on!$ be set with the Initia$iBe method.

Environent !ropert7 @MMDA

6esc 6escrripti iption on==

)pec )peci" i"es es a c!ie c!ient nt app! app!ic icat atio ion n spec speci" i"c c en(ironmenta! (a!ue.

)ets=

A 6S3R  (a!ue.  (a!ue.

%eturns=

A 6S3R  (a!ue.  (a!ue.

%emars=

A re readwrite pr propert$ wh which is is tr transmitted to to the MOCA ser(er. En,iron%ent is En,iron%ent  is the en(ironment string that gets hand!ed b$ the

254

en(ironment UhooU on the MOCA ser(er. ser(er. his is an app!ication speci"c (a!ue, which can be used to te!! the ser(er contet information, such as the user, user, the !anguage code, the session I6 Fif !ogged inG, and the c!ient de(ice code. he En,iron%ent propert$ En,iron%ent  propert$ is the on!$ wa$ to associate app!ication'speci"c contet information with the connection to the MOCA ser(er. #ote=

his propert$ can be set direct!$ or with the Initia$iBe method. Initia$iBe method.

AutoCoit !ropert7 @MMDA

6esc 6escrripti iption on==

Indi Indica cato torr for for the the MOC MOCA A ser ser(e (err to to ena enab! b!e e or or disab!e the Auto Commit feature of the MOCA ser(er.

)ets=

A 6OO (a!ue 6OO (a!ue

%eturns=

A 6OO (a!ue. 6OO (a!ue.

%emars=

A readw dwrite ite propert$. If set to % %, the MOC MOCA  ser(er wi!! automatica!!$ commit the transaction upon eecution of each command. If set to
6efau!t (a!ue is %.

Met/ods Initialie Met/od @MMDA

6esc 6escrripti iption on==

sta stab! b!is ishe hes s a con conne nect ctio ion n with with the the MOC MOCA A ser( ser(er er.

)$nta=

daObj.Initia$iBe Qost#ame, Qost#ame, &ort#umber, n(ironment! n(ironment!

&arameters=

  daO# An  An obje object ct (ariab (ariab!e !e iden identif tif$ing $ing the 6ataAccess object.  ost2  ost2ame ame  A  A str string ing (a!ue (a!ue iden identif tif$ing $ing the name name of the host to connect to.  "or  "ort2u t2um#e m#er  r ''A ''A short (a!ue identif$ing the port number to connect to.  Enviro  Environme nment nt''An ''An app!ication speci"c string

255

 (a!ue.  (a!ue. his (a!ue (a!ue can be a #// #// string string.. F)ee F)ee the n(ironment propert$G %emars=

sed the Initia$iBe method Initia$iBe method to estab!ish a connection to the MOCA ser(er. he 8ostNa%e and 8ostNa%e and ortN)%*er  parameters  parameters de"ne the MOCA ser(er to connect to. he En,iron%ent parameter En,iron%ent  parameter is app!ication de"ned. It can be set at a !ater time b$ setting the En,iron%ent propert$ En,iron%ent  propert$ (a!ue. pon successfu! comp!etion of this method, the c!ient app!ication is connected to the MOCA ser(er. he connection wi!! be maintained unti! the C$ose method is in(oed.

#ote=

In(ocations of the Initia$iBe method Initia$iBe method on a connected c!ient, wi!! cause the eisting connection to c!ose and a new connection to be estab!ished.

E:e0ute Met/od @MMDA

6esc 6escrripti iption on==

ec ecut utes es a com comma mand nd on the the MOC MOCA A ser ser(e (err.

)$nta=

Moca%et)ts  daObj.E+ec)te Command, Command, %ecordset, rroret, %ecordset-idth! %ecordset-idth !

%eturns=

he MOCA ser(er return st status as a !o !ong.

&arameters=

  daO# An  An obje object ct (ariab (ariab!e !e iden identif tif$ing $ing the 6ataAccess object. Command A  A stri string ng (a!u (a!ue e spec specif$ if$ing ing the command to eecute on the MOCA ser(er.  Record  Recordset seto opti ptiona onal l An  An object object (ariab (ariab!e !e identif$ing the Recordset object Recordset object created b$ the 6ataAccess object.  ErrorT  ErrorTe*t e*to opti ptiona onal l A  A str string ing (ariab! (ariab!e e rece recei(in i(ing g the error tet returned b$ the MOCA M OCA ser(er process.  Record  Recordset setDi Didth dth'' ''optional optional''An ''An object (ariab!e identif$ing the Recordset object Recordset object that gi(es information about the co!umns returned in the main recordset. recordset. he "e!ds "e!ds in the %ecordset-idth %ecordset-idth object inc!ude=  @ield2  @ield2ame ame

he name of the co!umn.

 Ma*Bef  Ma*Befned nedL L

he !ength of the co!umn in the

256

en

database.

 Ma*Act  Ma*Actual ualLe Le n

he ma data !ength actua!!$ returned.

%emars=

sed to eecute a command on the MOCA ser(er. ser(er. he command wi!! be sent to the MOCA ser(er and the MOCA ser(er wi!! perform the eecution. he MOCA ser(er wi!! return a moca data resu!t set to the 6ataAccess object. he moca6ata%es set wi!! be copied into an A6O recordset object and returned to the c!ient.

#otes=

he returned recordset wi!! be UdisconnectedU and opened. he recordset wi!! ha(e the fo!!owing propert$ settings= 9ursor!ocationP 9ursorVypeP !oc3VypeP Ccti Cctive ve9o 9onn nnec ecti tion onP P 0ourceP

CdUse9lient Cd"pen0tatic Cd!oc3Oatch"ptimistic 1U!! 1U!! 1U!!

If the MOCA ser(er returns an empt$ resu!t set, the recordset wi!! sti!! be disconnected and open. It ma$ or ma$ not ha(e an$ "e!ds de"ned, depending on the resu!t set returned. he E+ec)te method must be ca!!ed on a connected c!ient. If the c!ient is disconnected, the method wi!! throw an eception. Close Met/od @MMDA

6esc 6escrripti iption on==

C!os C!oses es the the con conne nect ctio ion n with with the the MOCA MOCA ser ser(e (err.

)$nta=

daO#. daO#.C$ose

 

&arameters= %emars=

  daO# An  An obje object ct (ariab (ariab!e !e iden identif tif$ing $ing the 6ataAccess object. sed to to terminate th the connection to to the MOCA ser(er and free up an$ associated s$stem resources. his method shou!d be ca!!ed after a!! commands ha(e been eecuted on the MOCA  ser(er. ser(er. If the c!ient is not current!$ connected, this method wi!! return a success status.

257

Data T7pe Conversion he MM6A component is responsib!e for con(erting MOCA data t$pes to A6O recordset data t$pes. he fo!!owing tab!e shows the con(e con(ers rsio ion n of each each data data t$pe t$pe.. #ote #ote== MOCA MOCA on!$ on!$ supp suppor orts ts a subset of the A6O data t$pes. MOCA 6ata $pe

A6O 6ata $pe

#A   AdArra$  AdArra$

Comment  oined  oined in a !ogica! !ogica! O% togeth together er with with another t$pe to indicate that the data is a safe'arra$ of that t$pe F6+W&HA%%AWG.

#A

Ad+igInt

An 'b$te signed integer F6+W&HIG.

COMW&H+I#A%W

Ad+inar$

A bi binar$ (a (a!ue F6 F6+W&H+W)G.

#A

Ad+oo!ean

A +oo!ean (a!ue F6+W&H+OO/G.

#A 

#A 

ad+$%ef 

 oined  oined in a !ogica! !ogica! O% togeth together er with with another t$pe to indicate that the data is a pointer to data of the other t$pe F6+W&H+W%
ad+)% 

 A nu!! nu!!'te 'termi rminat nated ed charact character er stri string ng FnicodeG F6+W&H+)%G.

COMW&H)%I#4 COMW&HCQA% 

adChar

A )tring (a!ue F6+W&H)%G.

COMW&H3 #A  adCurrenc$

 A curre currenc$ nc$ (a!ue (a!ue F6+W& F6+W&HC HCWG. WG. Currenc$ is a "ed'point number with four digits to the right of the decima! point. It is stored in an 'b$te signed integer sca!ed b$ 10,000.

ad6ate

 A 6ate 6ate (a!ue (a!ue F6+W& F6+W&H6 H6A AG. G. A date date is stored as a 6oub!e, the who!e part of  which is the number of da$s since 6ecember 80, 199, and the fractiona! part of which is the fraction of a da$.

ad6+6ate

 A date date (a!u (a!ue e F$$$ F$$$$mmd $mmddG dG F6+W&H6+6AG.

#A 

#A 

#A

ad6+ime

A time (a!ue FhhmmssG

258

F6+W&H6+IMG. COMW&H6AIM

 A date' date'tim time e stamp stamp F$$$$m F$$$$mmdd mddhhm hhmmss mss  Ad6+ime  Ad6+ime)ta )tam m p!us a fraction in bi!!ionthsG p F6+W&H6+IM)AM&G.

#A 

COMW&H
#A #A 

#A 

ad6ecima!

 An eact eact numeri numeric c (a!ue (a!ue with with a "ed "ed precision and sca!e F6+W&H6CIMA/G.

ad6oub!e

 A doub! doub!e'p e'preci recisio sion n Poat Poating ing point point (a!ue (a!ue F6+W&H%G.

admpt$

#o (a!ue was speci"ed F6+W&HM&WG.

adrror

A 82'bit error code F6+W&H%%O%G.

ad4I6

 A g!oba g!oba!!$ !!$ uniBu uniBue e ident identi"e i"err F4I6G F4I6G F6+W&H4I6G.

adI6ispatch

 A point pointer er to to an an I6is I6ispat patch ch inte interfac rface e on on an O/ object F6+W&HI6I)& F6+W&HI6I )&ACQG. ACQG.

COMW&HI#W COMW&H)QO% adInteger

A ]'b$te signed integer F6+W&HI]G.

COMW&H/O#4 COMW&HI# #A 

#A

#A 

#A

Ad/ong*ar+ina  A !ong !ong bina binar$ r$ (a!u (a!ue e F&aram F&aramete eterr obje object ct r$ on!$G.  Ad/ong*  Ad/ong*arCh arChar ar

 A !ong !ong )tri )tring ng (a!u (a!ue e F&aram F&aramete eterr objec objectt on!$G.

Ad/ong*ar-Ch  A !ong !ong nu!! nu!!'te 'termi rminat nated ed string string (a!ue (a!ue ar F&arameter object on!$G.

#A  ad#umeric

#A

 A point pointer er to to an an In Innow nown n inte interfac rface e on on an O/ object F6+W&HI#\#O-#G.

adInnown

ad)ing!e

 An eact eact numeri numeric c (a!ue (a!ue with with a "ed "ed precision and sca!e F6+W&H#M%ICG. A sing!e'precision Poating point (a!ue

259

F6+W&H%]G. #A

ad)ma!!Int

A 2'b$te signed integer F6+W&HI2G.

#A

adin$Int

A 1'b$te signed integer F6+W&HI1G.

#A

Adnsigned+ig  An 'b$ 'b$te te unsign unsigned ed int intege egerr Int F6+W&HIG.

#A 

adnsignedInt

 A ]'b$t ]'b$te e unsi unsigne gned d integ integer er F6+W&HI]G.

#A

Adnsigned)m  A 2'b$t 2'b$te e unsi unsigne gned d integ integer er a!!Int F6+W&HI2G.

#A

Adnsignedin  A 1'b$t 1'b$te e unsi unsigne gned d integ integer er  $Int  $Int F6+W&HI1G.

#A 

adser6e"ned

 A user user'de" 'de"ned ned (ariab (ariab!e !e F6+W&H6G.

#A

ad*ar+inar$

A binar$ (a!ue F&arameter object on!$G.

#A

ad*arChar

A )tring (a!ue F&arameter object on!$G.

#A 

ad*ariant

 An Auto Automat mation ion *ariant ariant F6+W&H*A%IA#G.

ad*ector

 oined  oined in a !ogica! !ogica! O% togeth together er with with another t$pe to indicate that the data is a 6+*CO% structure, as de"ned b$ O/ 6+, that contains a count of e!ements and a pointer to data of the other t$pe F6+W&H*CO%G.

ad*ar-Char

 A nu!! nu!!'te 'termi rminat nated ed nicod nicode e charac character ter string F&arameter object on!$G.

ad-Char

 A nu!! nu!!'te 'termi rminat nated ed nicod nicode e charac character ter string F6+W&H-)%G.

#A 

#A 

#A 

260

D E * E & O ! I N G

M O C A

C O M ! O N E N T S

I N

- A * A

)istor7 of -ava support

Developin= MOCA Developin= 0oponents and appli0ations in -ava

C/apter 

1,

This chapter provides descriptions o  MOCA  MOCAKs ava ava suppo support, rt, and ho& to develo develop p  MOCA  MOCA com compon ponent ents s and and appli applicat cation ions s in the ava pro+rammin+ pro+rammin+ lan+ua+e!

MOCA MOCA,, in ear! ear!ie ierr (ers (ersio ions ns,, had had prim primit iti( i(e e supp suppo ort for for a(a a(a components components.. here were were inherent inherent !imitations !imitations on what cou!d cou!d be done in a(a, and the capabi!it$ essentia!!$ went unused, unti! it was remo(e remo(ed d some some $ears $ears !ater. !ater. %ecent %ecent!$ !$,, suppor supportt for for a(a a(a components has been added into MOCA again. #ote= un!ess otherwise stated, a!! of the c!asses and interfaces ment mentio ione ned d in this this chap chapte terr are are !oca !ocate ted d in the the ja(a ja(a pac pacag age e com.redprairie.moca .
ritin= a Coponent MOCA MOCA comp compon onen ents ts in a(a a(a are are imp!e imp!eme ment nted ed as simp simp!e !e ja(a ja(a c!asses. c!asses. MOCA uses rePect rePection ion to "nd c!asses c!asses and methods methods to in(oe based on a component component de"nition. de"nition. Much !ie other other t$pes, a MOCA a(a component de"nition inc!udes the c!ass name, the meth method od name, name, and and a !ist !ist of argu argume ment nts. s. ach ach comp compon onen entt in(o in(oca cati tion on caus causes es MOCA MOCA to "nd "nd the the c!as c!ass s and and meth method od F(ia F(ia rePectionG, optiona!!$ instantiate the c!ass, and ca!! the method with arguments "!!ed "!!ed in from the stac. stac. If the method is a c!ass method FstaticG, the c!ass is ne(er instantiated. packa$e com%redprairie%dl(%samplesH 311  1 his is a sample MOCA server6side component written in ava%  13

public class &trin$Etils  311 1 ?eturn an array of strin$s consistin$ of the first ar$ument, 1 split on the re$ular e(pression $iven by the second ar$ument% 13 public &trin$- split&trin$&trin$ ar$, &trin$ re$e(  return ar$%splitre$e(H F F

 A componen componentt de"nit de"nition ion that used used that eamp!e eamp!e c!ass might might !oo  !ie this= :commandG  :nameGsample split string  :HnameG :HnameG  :descriptionG Split a string on a rege$.:HdescriptionG  :typeGJava Method  :HtypeG :HtypeG  :classG0trin5Utils:HclassG  :methodG splitString  :HmethodG :HmethodG  :ar5ument name= so#re alias= orig   datatype = string   reTuired= yesG  :Har5umentG  :ar5ument name= delimiter   default$value= - datatype= string  G G Vhe #elimiter  :Har5umentG :HcommandG

In order for that component de"nition to be found, it needs to be a part of a component !ibrar$ that de"nes the root pacage for the component. :component$levelG :component$levelG  :nameG
-hen in(oed, the command wou!d produce the fo!!owing output M&.#/ sample split strin$ where source'AAA,888,testin$,),+,L' 1M&.#/ 3 4(ecutin$%%% &uccess5 result 66666666 AAA 888 testin$ ) +

262

L * ?ows Affected M&.#/

#ote #ote that that we ne(e ne(err had had to de" de"ne a resu resu!t !t set set or gi(e gi(e an$ an$ info inforrmati mation on to MOCA MOCA about about data data t$pe t$pes s of co!u co!umn mns. s. If a component returns a primiti(e Fnumeric or stringG resu!t or an arra$ of primiti(e resu!ts, MOCA wi!! name the resu!t co!umn ?resu!t@ and gi(e it a a data t$pe corresponding to the de"ned data t$pe of the primiti(e object. If $ou want to pro(ide more contro! o(er the t$pes of resu!ts returned, more more sophisticated techniBues are reBuired. d  $ou>d need need to to retu return rn a t$pe t$pe of Moca%e Moca%esu! su!ts ts object object..

Mo0aResults In order to pro(ide more contro! o(er resu!ts returned from a component, a more comp!e object must be returned from the component. component. One wa$ to do that is b$ returning returning a Moca%esu!t Moca%esu!ts s object. object. Moca%esu!t Moca%esu!ts s represents represents a MOCA resu!t resu!t set Fsimi!ar Fsimi!ar to moca moca6a 6ata ta%e %es s in CG, CG, and and can can be used used to read read thro throug ugh h and and process resu!ts of commands as we!! as to encode the output of a component. here are a number of Moca%esu!ts imp!ementations, as shown in this c!ass hierarch$=

263

he thre hree interface aces,  MocaRe  MocaResul sults ts,,  Modifa  Modifa#le #leRes Result ults s and  Edita#  Edita#leR leResu esults lts represent  represent the read'on!$ and read'write (ersion of MOCA resu!ts. Moca%esu!ts has methods to Buer$ the resu!t set for its co!umn names and data t$pes as we!! as to read the resu!t data. Modi"ab!e%esu!ts adds the abi!ibit to add rows to a resu resu!t !t set. set. s better than t$ing $our component component to a particu!ar imp!ementation c!ass. Qere Qere>s >s an eamp eamp!e !e of a a(a a(a meth method od that that prod produc uces es mu!t mu!tip ip!e !e co!umnrow output= packa$e com%redprairie%dl(%samplesH import com%redprairie%moca%Moca?esultsH import com%redprairie%moca%4ditable?esultsH

264

import com%redprairie%moca%MocaypeH 311  1 his is a sample MOCA server6side component written in ava%  13 public class &trin$Etils  311 1 ?eturn results containin$ key3value pairs% 1 2param ar$ 13 public Moca?esults split&trin$Mappin$MocaConte(t moca, &trin$ ar$  4ditable?esults res  moca%new?esultsH res%addColumn"key", Mocaype%&?INBH res%addColumn"value", Mocaype%&?INBH &trin$- elements  ar$%split","H for int i  :H i T elements%len$thH iDD  &trin$- keyGalue  elementsi-%split"UU0"H   res%add?owH res%set&trin$Galue"key", keyGalue:-H res%set&trin$Galue"value", keyGalue)-H F return resH F

M&.#/ sample split mappin$ where source'k)0v),k+0v+,kL0foo' 1M&.#/ 3 4(ecutin$%%% &uccess5 key 666 k) k+ kL

value 66666 v) v+ foo

L ?ows Affected M&.#/

her here e is anot anothe herr wa$ wa$ of hand hand!i !ing ng resu resu!t !ts s that that need need to be structur structured. ed. If $ou de"ne de"ne $our compone component nt method method to return return a non'primiti(e a(a object For an arra$ of themG, that object wi!! be Bueried for its properties, a(a+eans st$!e, and MOCA resu!ts wi!! be obtained obtained b$ pub!ishin pub!ishing g those propert properties. ies. If we want to return the same two co!umns as in the pre(ious eamp!e, we cou!d de"ne a c!ass that has those two properties Fin this case, read'on!$ properties wi!! doG. public static class Mappin$?esults  public Mappin$?esults&trin$ key, &trin$ value  @key  keyH @value  valueH F

265

public &trin$ $etVey  return @keyH F public &trin$ $etGalue  return @valueH F

F

private final &trin$ @keyH private final &trin$ @valueH

hen we can rede"ne our component method to return instances of this c!ass instead of instances of )imp!e%esu!ts= public Mappin$?esults- split&trin$Mappin$&trin$ ar$  #ist list  new Array#istH &trin$- elements  ar$%split","H for int i  :H i T elements%len$thH iDD  &trin$- keyGalue  elementsi-%split"UU0"H list%addnew Mappin$?esultskeyGalue:-, keyGalue)-H F return Mappin$?esults- list%toArraynew Mappin$?esults:-H F

he (a!ue of using the ?bean resu!ts@ approach is that, un!ie Moca%esu!ts, the t$pes of data items added to a resu!t set is dete determ rmin ined ed at comp compi!e i!e time. time. A!so A!so,, if $ou ha(e a numb number er of  compo componen nentt method methods s that that return return simi!ar simi!ar resu! resu!ts, ts, the$ the$ can be coded to use the same resu!ts c!ass and a(oid the dup!ication of  resu!t set initia!iXation code.

Mo0aConte:t
266

to the constructor can be used throughout the !ife of the component object. 2. A compo mponent method can optiona iona!!!$ de"ne its "rst parame parameter ter to be of t$pe t$pe MocaCon MocaConte tet. t. If that metho method d de"nit de"nition ion eists eists,, a conte contet t object object wi!! be passed passed to the method upon component in(ocation 8. An$ method method can get get the ?curr ?current@ ent@ contet contet from from the MOCA  !ibraries b$ using the Mocati!s.currentContetFG method.
E:0eption E:0eptio n )andlin= #orma! eecution of a a(a component wi!! resu!t in a resu!ts object being created and a status of eO\ F0G being returned to the MOCA run'time run'time eecuti(e. If a component component wants to signa! signa! an error condition to MOCA, that is hand!ed through the use of a(a eceptions. In order to communicate a nown error condition to MOCA Fand ther theref efor ore e to the the c!ie c!ient nt app! app!ic icat atio ionG nG,, MOCA MOCA pro( pro(id ides es a base base eception c!ass ca!!ed Mocaception. Mocaception. In order to send an error code code to the the s$st s$stem em,, it is nece necess ssar ar$ $ to thro throw w an inst instan ance ce of  Mocaception out of $our method. It is common practice practice Fand a good good idea ideaGG to ete etend nd Moca Moca ce cept ptio ion n for for an$ an$ app! app!ic icat atio ion' n' speci"c use of MOCA eceptions. Qere>s an eamp!e eception that indicates a bad )tring format.

267

public class &trin$9ormat4(ception e(tends Moca4(ception  public static final int CO74  ++LH public &trin$9ormat4(ception&trin$ messa$e  superCO74, messa$eH F F

-e cou!d throw that eception when parsing our e$(a!ue pairs= public Moca?esults split&trin$Mappin$MocaConte(t moca, &trin$ ar$ throws &trin$9ormat4(ception  4ditable?esults res  moca%new?esultsH res%addColumn"key", Mocaype%&?INBH res%addColumn"value", Mocaype%&?INBH &trin$- elements  ar$%split","H for int i  :H i T elements%len$thH iDD  &trin$- keyGalue  elementsi-%split"UU0"H if keyGalue%len$th T +  throw new &trin$9ormat4(ception "missin$ delimiter " D elementsi-H F if keyGalue%len$th / +  throw new &trin$9ormat4(ception "too many delimiters " D elementsi-H F   res%add?owH res%set&trin$Galue"key", keyGalue:-H res%set&trin$Galue"value", keyGalue)-H F return resH F

hen hen,, situ situat atio ions ns wher where e a bad bad argu argume ment nt come comes s in wi!! wi!! caus cause e MOCA MOCA to go into into error error hand!ing hand!ing mode. mode. C ca!!ers ca!!ers that in(o in(oe e these commands wi!! get error code 228 from sr(InitiateCommand. M&.#/ sample split mappin$ where source'k)0v),k+0v+,kL0foo,k<' 1M&.#/ 3 4(ecutin$%%% 4rror5 4??O? ++L 6 missin$ delimiter k< M&.#/ sample split mappin$ where source'k)0v),k+0v+,kL0foo,k<00b' 1M&.#/ 3 4(ecutin$%%% 4rror5 4??O? ++L 6 too many delimiters k<00b M&.#/

 An$ comp compone onent nt metho method d that that throws throws an an ecept eception ion wi!! wi!! indica indicate te to MOCA MOCA that an error error conditio condition n has occurre occurred. d. An$ ecept eception ion thrown that does not etend Mocaception For

268

Moca Moca%u %unt ntime ime ce cept ptio ion'' n'''s 'see ee be!o be!owG wG wi!! wi!! come come bac bac as an unepected error, and the eception stac trace wi!! be put into the MOCA trace !og. MOCA a!so de"nes a few we!!'nown eceptions that are safe to catch ep!icit!$. 1ot;ound7Sception  corresponds to one of the two MOCA ?not found@ error codes= e#O_1"_8"`0_C;;79V7#  F'1]08G, or F710G. )ince these these (a!ues (a!ues are are used prett$ prett$ e08W_1"_8"`0_C;;79V e08W_1"_8"`0_C;;79V7# 7# F710G. much interchangeab!$, the same eception c!ass is used for both error code codes. s. A!so !so, UniTue9onstraint7Sception , !oc !ocated in the pac pacag age e com.redprairie.moca.dE , is used to indicate a database constraint has been (io!ated Ft$pica!!$ a primar$ e$ or foreign e$ constraintG. Qere>s an eamp!e of a common approach to hand!ing eceptions from MOCA command in(ocations= public int countOrder#inesMocaConte(t moca, &trin$ orderid throws Moca4(ception  try  Moca?esults res  moca%e(ecuteInline "list order lines where order@id  '" D orderid D "'"H int i  :H while res%ne(t iDDH return iH F catch Not9ound4(ception e  return :H F F

#ote that the method dec!ares that it throws Mocaception, $et it catches catches #ot< #ot
Runtie vs. C/e0ed E:0eptions here is a debate in the a(a wor!d about the concept of runtime and checed eceptions. Checed eceptions eceptions are dec!ared dec!ared in the throws c!ause of a method and must be dea!t with, either using a tr$catch b!oc or b$ dec!aring that $our ca!!ing method a!so throws throws the same same eceptio eception. n. +ecaus +ecause e this can get tiresom tiresome, e, epecia!!$ for some fair!$ simp!e aspects of the a(a !anguage, the a(a designers came up with runtime e*ceptions, e*ceptions, which don>t ha(e to be caught caught or dec!ared dec!ared.. he$ are just just a!!owed a!!owed to bubb!e out of an$ method on an$ c!ass. Most of the bui!t'in a(a runtime runtime

269

ecept eception ions s indica indicate te that that some some sort sort of progra programmi mming ng error error has occu occurr rred ed.. Chec Chece ed d ece ecept ptio ions ns in a(a a(a indi indica cate te that some some unforeseen error situation has arisen, such as a "!e not being wher where e we epe epect ct it to be, be, or some some ind ind of data databa base se erro errorr. +ecause of their use in hand!ing MOCA in(ocation errors, MOCA  uses uses checed checed ecepti eceptions ons for most operat operation ions. s. It is possib possib!e, !e, howe(er, to wrap a MOCAception in a runtime eception to a!!ow a !ow'!e(e! eception to bubb!e up out of a method without ha(ing to dec!are it e(er$where. he argume argument nt about about chece checed d (s. runtim runtime e ecept eception ions s for a(a a(a de(e!opment in genera! is somewhat be$ond the scope of this document, and probab!$ wou!dn>t be easi!$ reso!(ed, e(en it it were. were. MOCA has chosen chosen the checed checed eceptio eception n approach, approach, but a!!o a!!ow ws de(e de(e!!ope opers to wrap rap those hose chec heced ed ec ecept eptions ions in Moca% oca%un unti time me ce cept ptio ion n to a(o a(oid the the burde urden n of chec chece ed d eceptions, if desired.

-D%C Conne0tions One of the ad(antages of de(e!oping in a(a is that there are so man$ man$ goo good thir hird'p d'part art$ too! too!s s out out ther there e for for enab nab!ing !ing a(a a(a de(e!opment, and a !ot of industr$ eperience with eisting a(a too!s. too!s. Man$ too!s too!s eist to he!p de(e!oper de(e!opers s with hand!ing object object persi ersist sten ence ce,, creat eate and and eec eecut ute e datab atabas ase e Bue Bueries ries,, etc. tc. ni(er ni(ersa! sa!!$ !$,, a!! of those those too!s too!s need need to ha(e ha(e a 6+C databa database se connection to interact with the the database. -e now ha(e a 6+C' based database adapter for MOCA to a!!ow a(a code to obtain a  6+C  6+C Connecti Connection on object object to inter interact act with with the same datab database ase that that MOCA is using for its interactions. sing the MocaContet.getConnectionFG method, a reference to the acti(e acti(e MOCA databa database se connect connection ion can be obtain obtained. ed. hat hat conn connec ecti tion on can can be inter interac acte ted d with with as an$ an$ 6+C 6+C conn connec ecti tion on wou!d, and can e(en be used to enab!e third'part$ persistence too!s, too!s, such such as Qibern Qibernate ate Fwww Fwww.hiber .hibernat nate.o e.orgG rgG or )o!arm )o!armetr etric ic \O6O \O6O Fa 6O imp!ementation imp!ementationG. G. In fact, MOCA has pre!iminar pre!iminar$ $ support support for Qibernate Qibernate bui!t'in. bui!t'in. o obtain a Qibernate Qibernate session, session, use use the the com.redprairie.moca.dE.hiEernate.JiEernateVools.5et0ession methods. he$ !oo at the en(ironment (ariab!e QI+ QI+%# %#A AHM HMA& A&&I &I#4 #4) ) to dete determ rmin ine e wher where e to !oo !oo for for hibernate>s 3M/ mapping "!es.

270

-ava Client A00ess via Mo0aConne0tion
Advan0ed Topi0s
271

. E %

S E R * I C E S  

SOA! and eb Servi0e s

MOCA eb eb Servi0es Servi0es

C/apter 

11

This chapter descri#es MOCA De# Services  e*posin+ MOCA commands as &e# services throu+h the use o the SOA"  protocol!

MOCA is itse!f itse!f a form of a ser(ice'or ser(ice'oriente iented d architecture architecture.. ach component in a s$stem can be considered a pub!ished ser(ice, and a!! MOCA'based s$stems are based on being ab!e to in(oe MOCA ser(ices. ser(ices. (e chosen chosen to imp!ement our )OA& !a$er !a$er using a(a )er(!ets, and we can uti!iXe an$ a(a )er(!et'based web ser(er. he simp!est to insta!! and con"gure Fand one of the most hea(i!$ testedG is Apache>s free Tomcat  Tomcat  ser(er Fhttp<tomcat!apache!or+ http<tomcat!apache!or+G. G. Inst Insta!! a!!at atio ion n and con" con"gu gura rati tion on of  omcat or other )er(!et'based app ser(ers is be$ond the scope of  this document, and shou!d be considered a prereBuisite for using MOCA'based web ser(ices.

Definin= eb Servi0es MOCA MOCA>s web ser(ic ser(ice e !a$er !a$er is essen essentia tia!!$ !!$ a mappin mapping g betwee between n )OA& )OA& ca!!s ca!!s and and MOCA MOCA ca!!s. ca!!s. )OA& )OA& ca!!s ca!!s are are orga organi niXe Xed d into into ser(ices, ser(ices, which which ha(e operations. operations. hese rough!$ rough!$ correspon correspond d to c!asses and methods, from from an object'orien object'oriented ted point of (iew. (iew. ach ser(ic r(ice e oper peratio ation n must must ha(e ha(e a we!!' e!!'de de" "ned ned set of inpu inputt parame parameter ters, s, and must must ha(e ha(e a we!!'d we!!'de" e"ned ned output output struct structure ure..

272

. E %

S E R * I C E S  

)OA& )OA& ca!!s ca!!s and the epected epected input and output output struct structure ure are de"n de"ned ed b$ -)6/ -)6/,, a sche schema ma'b 'bas ased ed 3M/ 3M/ form format at that that de"n de"nes es ser(ice metadata. MOCA>s ser(ice in(ocation is much simp!er  MOCA commands are referr referred ed to and in(oed in(oed b$ a simp!e command command name. name. An$ argiment can be passed to an$ command, and, due to things !ie triggers and wrapped commands, the set of !ega! arguments is open'e open'ende nded. d. Comman Command d resu resu!ts !ts are simi!a simi!ar!$ r!$ open'en open'ended ded.. A  command can return an$ (a!ues to the ca!!er, and (er$ !itt!e of  the information about the command is we!!'de"ned, ecept b$ con(e con(ent ntio ion. n. In order order to brid bridge ge the gap betwee between n thes these e two two para paradi digm gms, s, we must must pro( pro(id ide e some some stru struct ctur ure e arou around nd MOCA  MOCA  command command in(ocations in(ocations.. he resu!t resu!t is the )er(ice )er(ice Con"gurati Con"guration on "!e.

Servi0e Confi=uration 9iles he MOCA ser(ice con"guration "!e is an 3M/ "!e that de"nes a web ser(ic ser(ice e in terms terms of the MOCA commands commands it eecute eecutes. s. In order to de"ne a ser(ice, $ou must de"ne a ser(ice name, an operation name, input arguments, a command to in(oe, and output resu!ts. )amp!e )er(ice Con"g
273

. E %

S E R * I C E S  

if  @dwnld_seT and @run_tran_fl5 and @run_tran_fl5 = FVF >  sl_process dwnld where dwnld_seT = @dwnld_seT and commit_step = $ and user_id = FF and dwnld_stat_cd = F7/8"9F A  puElish data where dwnld_seT=@dwnld_seT   ]]G:HcommandG :output multirow=BfalseBG :field name=Bdownload0eTB column=Bdwnld_seTB type=BdouEleB nullaEle=BfalseBHG   :HoutputG   :HoperationG   :HserviceG :Hservice$confi5G

his eamp!e demonstrates a ser(ice FhubCommand)er(iceG that de"n de"nes es a sing! sing!e e oper operat atio ion n Fpro Fproce cess ssIn Inbo boun und3 d3M/ M/6a 6ata taG, G, and and returns a sing!e data e!ement named down!oad)eB, which comes from the dwn!dHseB co!umn of the resu!t set returned from the command= sl_handle inEound_data where data = @data and native_nam = @native_nam and sys_id = @sys_id and dwnld_info = @dwnld_info and run_tran_fl5 = @run_tran_fl5 and Sml_fl5 = FVF  if  @dwnld_seT and @run_tran_fl5 and @run_tran_fl5 = FVF >  sl_process dwnld where dwnld_seT = @dwnld_seT and commit_step = $ and user_id = FF and dwnld_stat_cd = F7/8"9F A  puElish data where dwnld_seT=@dwnld_seT

/et>s go through each e!ement of the con"guration= :NSml version=B.%BNG :L#"9V6/7 service$confi5 060V7D Bservice$confi5.dtdBG

#eeded to mae this a (a!id 3M/ "!e. he 6OCW& e!ement is used used for for (a!idat (a!idation ion b$ the 3M/ parser parser.. he curren currentt ser(ic ser(ice' e' con" con"g. g.dt dtd d "!e "!e is atta attach ched ed at the the end end of this this docu docume ment nt,, for for reference.

274

. E %

S E R * I C E S  

:service$confi5G

he he Zser Zser(i (ice ce'c 'con on" "gT e!em e!emen entt is used used to deno denote te that that this this docu docume ment nt cont contai ains ns a ser( ser(ic ice e con" con"gu gura rati tion on.. ach ach ser( ser(ic ice e con" con"gu gura rati tion on "!e "!e must must cont contai ain n eac eact! t!$ $ one one ser( ser(ic ice' e'co con" n"g g e!ement. e!ement. he ser(ice'c ser(ice'con"g on"g e!ement e!ement can can contain contain one or more ser(ice e!ements. :service name=BhuE9ommand0erviceBG

he ser(ice e!ement e!ement de"nes a web ser(ice. ser(ice. A ser(ice must must ha(e a name F3M/ attribute= nameG, and can optiona!!$ ha(e the pac3a5e and class attributes. he ser(ice name is the de"ned name of the web ser(ice, and wi!! appear in generated -)6/ as the )OA& ser(ice ser(ice name. he pacage pacage and c!ass c!ass attributes attributes of the ser(ice ser(ice e!ement are used b$ the MOCA web ser(ice generator code to bui!d bui!d temporar temporar$ $ c!asse c!asses s to ho!d the ser(ice ser(ice imp!eme imp!ementi ntion. on. If  omitte omitted, d, MOCA uses uses defau!ts defau!ts based based on the ser(ice ser(ice name. name. In genera!, it is usua!!$ not necessar$ to de"ne c!ass and pacage names on $our ser(ices. :operation name=BprocessRnEoundD!#ataBG

he operation e!ement de"nes de"nes a )OA& )OA& operation or action. he operat operation ion name name F3M/ F3M/ attrib attribute ute== nameG wi!! appear in generated -)6/ as an a(ai!ab!e )OA& action to be performed. :inputG :ar5ument :ar5ument :ar5ument :ar5ument :ar5ument :HinputG

name=BdataB type=Bstrin5B nullaEle=BfalseBHG name=Bnative_namB type=Bstrin5B nullaEle=BfalseBHG name=Bsys_idB type=Bstrin5B nullaEle=BfalseBHG name=Bdwnld_infoB type=Bstrin5B nullaEle=BtrueBHG name=Brun_tran_fl5B type=Bstrin5B nullaEle=BtrueBHG

he input e!ement de"nes input arguments to the named ser(ice operation operation.. he input e!ement e!ement can ha(e Xero Xero or more more argument argument e!ements e!ements under under it. ach argument argument e!ement e!ement must must ha(e a name name and and t$pe t$pe de"n de"ned ed F3M/ F3M/ attr attrib ibut utes es== name  an and typeG. he he name name attribute must be a !ega! identi"er for MOCA and a(a, and must not be a reser(ed for either Fe.g. where, pri(ate, if, forG. he (a!id t$pes are= inte5er

9"DV6/_!"12

 An inte integer ger numeric numeric (a!ue (a!ue

douEle

9"DV6/_;!"CV

 A doub! doub!e'pr e'preci ecisio sion n Poat Poating ing point point numeri numeric c (a!ue (a!ue..

275

. E %

S E R * I C E S  

strin5

9"DV6/_0V8R12  A strin string g (a!ue (a!ue

Eoolean

9"DV6/_;!C2

 A boo!e boo!ean an (a!u (a!ue. e.

ach argument can optiona!!$ de"ne a co!umn name to be used for the argume argument nt (a!ue (a!ue in the MOCA s$nta s$nta F3M/ F3M/ attrib attribute ute== co!umn attribute is omitted, the argument name is columnG. If the co!umn used used both both as the the )OA& )OA& oper operat atio ion n argu argume ment nt name name,, and and the the MOCA MOCA (ariab (ariab!e !e name name.. ach ach argum argumen entt can can a!so a!so spec specif if$ $ the the nullaEle attribute, which, if fa!se, forces the )OA& !ibrar$ to (erif$ that the input argument is is present and non'nu!!. If an argument argument is not nu!!ab!e and it is not present in the )OA& reBuest, a )OA& error is generated. :commandG:L[9#CVC[ . . . ]]G:HcommandG

he command e!ement contains the MOCA s$nta to be eecuted when the )OA& reBuest corresponding to this ser(ice operation is recei recei(e (ed. d. ach ach input input argum argumen entt is made made a(ai a(ai!ab !ab!e !e on the the MOCA stac as a (ariab!e, and the command is eecuted eecuted once. If  the command eecutes norma!!$, it commits the transaction as epected, and the resu!t is processed according to the ZoutputT e!ement Fdescribed be!owG :output multirow=BfalseBG :field name=Bdownload0eTB column=Bdwnld_seTB type=BdouEleB nullaEle=BfalseBHG :HoutputG

he output e!ement de"nes the output of a web ser(ice in terms of the resu!t resu!t set that is returned from from the ser(ice ser(ice command. he output output e!ement e!ement has one boo!ean attribute, attribute, mu!tirow mu!tirow,, which, which, if  true, de"nes the output of the ser(ice as an arra$ of the gi(en "e!ds. Otherwise, the ser(ice ser(ice output is de"ned de"ned as a sing!e object with the gi(en gi(en "e!ds. "e!ds. he output output e!ement e!ement can contain contain Xero Xero or more "e!d e!ements, each of which has a name F3M/ attribute= nameG, an optiona! MOCA resu!t co!umn name F3M/ attribute= co!um co!umnG nG,, a data data t$pe t$pe F3M/ F3M/ attr attrib ibut ute= e= t$pe t$peG, G, and and a nu!! nu!!ab ab!e !e indicator indicator F3M/ F3M/ attribute= attribute= nu!!ab!eG nu!!ab!eG.. If the co!umn co!umn attribute attribute is speci"ed, the co!umn is retrie(ed from the command resu!t and returned from from the web ser(ice ser(ice as the named "e!d. If the co!umn

276

. E %

S E R * I C E S  

attribute is !eft unspeci"ed, the "e!d name is used to retrie(e the data data instea instead. d. he he nu!! nu!!ab ab!e !e attr attrib ibut ute, e, as with with the the argu argume ment nt de"nition, speci"es whether the gi(en "e!d is a!!owed to be nu!!.

%uildin= t/e eb Servi0e Appli0ation  After  After de(e!o de(e!opin ping g the ser(ic ser(ice e descri descripto ptorr, it must must be bui!t bui!t into into a runnin ning web app!ication. As current!$ distribut ibute ed, /)6I%bui!d.m! contains the necessar$ code to bui!d a MOCA  web ser(ice ser(ice app!icatio app!ication. n. It is contro!!ed contro!!ed b$ a simp!e pr proper operties ties "!e, /)6I%webser(ice /)6I%webser(ices.properties. s.properties. pathWenv%MOCA7I?F3src3webservicesWenv%7C&7I?F3src3webserivcesU Wenv%I?F3src3webservicesWenv%#4&7I?F3src3webservices appnameprod hostlocalhost port<:::

he path is the set of directories that are scanned for ser(ice con"g "!es Fnamed V.s(c.m!G. he host and port are con"gured into the web app!ication to !et it now how to access MOCA  when web ser(ices ser(ices are in(oed. he appname is the name of the generated web app!ication F.war "!eG. -hen a ser(ice is in(oed using the MOCA web ser(ice app!ication>s %/, it parses the web ser(ice reBuest, initiates a connection to the compi!ed'in host and port, and eecutes the appropriate command, according to the con"gured ser(ices. o bui!d the web ser(ice, just run the command ant wsEuild

in /)6I /)6I%. %. Ant Ant wi!! wi!! eec eecut ute e the the MOCA MOCA wsbui! wsbui!d d proc proces ess, s, passing it appropriate (a!ues according to $our webser(ic webser(ices.pr es.proper operties ties "!e. "!e. If e(er$thing e(er$thing goes we!!, we!!, the resu!t wi!! be a "!e appname .war, where appname is appname is the (a!ue $ou put into the appname appname "e!d "e!d of the webser(ices webser(ices.pro .properti perties es "!e. his -A% "!e F-eb A%chi(eG is p!aced into the webapps director$ of  tomcat, and the app!ication is dep!o$ed and read$ to run.

Callin= eb Servi0es -hen a MOCA web ser(ice is dep!o$ed, the %/ to access it is !ocated at http33hostname port 3appname3services3serviceName 3appname3services3serviceName

o see the -)6/ for the ser(ice, append _wsd! to the %/ =

277

. E %

S E R * I C E S  

http33hostname port 3appname3services3serviceNameXwsdl 3appname3services3serviceNameXwsdl

In our eamp!e, this is the resu!ting -)6/ = TX(ml version")%:" encodin$"E96;"X/ Twsdldefinitions tar$etNamespace"http33services%redprairie%com3" (mlnstns"http33services%redprairie%com3" (mlnswsdlsoap"http33schemas%(mlsoap%or$3wsdl3soap3" (mlnssoap)+"http33www%wL%or$3+::L3:>3soap6envelope" (mlnsns)"http33$en%webservices%redprairie%com" (mlns(sd"http33www%wL%or$3+::)3YM#&chema" (mlnssoapenc))"http33schemas%(mlsoap%or$3soap3encodin$3" (mlnssoapenc)+"http33www%wL%or$3+::L3:>3soap6encodin$" (mlnsns+"http33webservices%redprairie%com" (mlnssoap))"http33schemas%(mlsoap%or$3soap3envelope3" (mlnswsdl"http33schemas%(mlsoap%or$3wsdl3"/   Twsdltypes/ T(sdschema (mlns(sd"http33www%wL%or$3+::)3YM#&chema" attribute9orm7efault"Pualified" element9orm7efault"Pualified" tar$etNamespace"http33services%redprairie%com3"/ T(sdelement name"processInboundYM#7ata"/   T(sdcomple(ype/   T(sdsePuence/ T(sdelement ma(Occurs")" minOccurs")" name"data" nillable"true" type"(sdstrin$"3/ T(sdelement ma(Occurs")" minOccurs")" name"native@nam" nillable"true" type"(sdstrin$"3/ T(sdelement ma(Occurs")" minOccurs")" name"sys@id" nillable"true" type"(sdstrin$"3/ T(sdelement ma(Occurs")" minOccurs")" name"dwnld@info" nillable"true" type"(sdstrin$"3/ T(sdelement ma(Occurs")" minOccurs")" name"run@tran@fl$" nillable"true" type"(sdstrin$"3/   T3(sdsePuence/   T3(sdcomple(ype/   T3(sdelement/ T(sdelement name"processInboundYM#7ata?esponse"/   T(sdcomple(ype/   T(sdsePuence/ T(sdelement ma(Occurs")" minOccurs")" name"out" nillable"true" type"ns)processInboundYM#7atahubCommand&ervice@processInboundYM#7ata ?esult"3/   T3(sdsePuence/   T3(sdcomple(ype/   T3(sdelement/ T(sdelement name"&ervice4(ception" type"ns+&ervice4(ception"3/ T(sdelement name"Eseroken" type"ns+Eseroken"3/   T3(sdschema/ T(sdschema (mlns(sd"http33www%wL%or$3+::)3YM#&chema" attribute9orm7efault"Pualified" element9orm7efault"Pualified" tar$etNamespace"http33$en%webservices%redprairie%com"/   T(sdcomple(ype name"processInboundYM#7atahubCommand&ervice@processInboundYM#7ata?esu lt"/   T(sdsePuence/ T(sdelement minOccurs":" name"download&eP" type"(sddouble"3/   T3(sdsePuence/   T3(sdcomple(ype/   T3(sdschema/ T(sdschema (mlns(sd"http33www%wL%or$3+::)3YM#&chema" attribute9orm7efault"Pualified" element9orm7efault"Pualified" tar$etNamespace"http33webservices%redprairie%com"/ T(sdcomple(ype name"&ervice4(ception"/

278

. E %

S E R * I C E S  

 

T(sdsePuence/ T(sdelement minOccurs":" name"code" type"(sdint"3/   T3(sdsePuence/   T3(sdcomple(ype/ T(sdcomple(ype name"Eseroken"/   T(sdsePuence/ T(sdelement minOccurs":" name"password" nillable"true" type"(sdstrin$"3/ T(sdelement minOccurs":" name"username" nillable"true" type"(sdstrin$"3/   T3(sdsePuence/   T3(sdcomple(ype/   T3(sdschema/   T3wsdltypes/ Twsdlmessa$e name"processInboundYM#7ata?ePuestJeaders"/ Twsdlpart name"Eseroken" element"tnsEseroken"3/   T3wsdlmessa$e/ Twsdlmessa$e name"processInboundYM#7ata?ePuest"/ Twsdlpart name"parameters" element"tnsprocessInboundYM#7ata"3/   T3wsdlmessa$e/ Twsdlmessa$e name"&ervice4(ception"/ Twsdlpart name"&ervice4(ception" element"tns&ervice4(ception"3/   T3wsdlmessa$e/ Twsdlmessa$e name"processInboundYM#7ata?esponse"/ Twsdlpart name"parameters" element"tnsprocessInboundYM#7ata?esponse"3/   T3wsdlmessa$e/ Twsdlportype name"hubCommand&erviceortype"/ Twsdloperation name"processInboundYM#7ata"/ Twsdlinput name"processInboundYM#7ata?ePuest" messa$e"tnsprocessInboundYM#7ata?ePuest"3/ Twsdloutput name"processInboundYM#7ata?esponse" messa$e"tnsprocessInboundYM#7ata?esponse"3/ Twsdlfault name"&ervice4(ception" messa$e"tns&ervice4(ception"3/   T3wsdloperation/   T3wsdlportype/ Twsdlbindin$ name"hubCommand&erviceJttp8indin$" type"tnshubCommand&erviceortype"/ Twsdlsoapbindin$ style"document" transport"http33schemas%(mlsoap%or$3soap3http"3/ Twsdloperation name"processInboundYM#7ata"/ Twsdlsoapoperation soapAction"urnprocessInboundYM#7ata"3/ Twsdlinput name"processInboundYM#7ata?ePuest"/ Twsdlsoapbody use"literal"3/   Twsdlsoapheader messa$e"tnsprocessInboundYM#7ata?ePuestJeaders" part"Eseroken" use"literal"/   T3wsdlsoapheader/   T3wsdlinput/ Twsdloutput name"processInboundYM#7ata?esponse"/ Twsdlsoapbody use"literal"3/   T3wsdloutput/ Twsdlfault name"&ervice4(ception"/ Twsdlsoapfault name"&ervice4(ception" use"literal"3/   T3wsdlfault/   T3wsdloperation/   T3wsdlbindin$/ Twsdlservice name"hubCommand&ervice"/ Twsdlport name"hubCommand&erviceJttport" bindin$"tnshubCommand&erviceJttp8indin$"/   Twsdlsoapaddress location"http33localhost;:;:3prod3services3hubCommand&ervice"3/   T3wsdlport/   T3wsdlservice/ T3wsdldefinitions/

279

. E %

S E R * I C E S  

he generated -)6/ can be processed b$ a number of other )OA& c!ients, inc!uding Microsoft .#, and a number of other )OA& )OA& c!ie c!ient nts, s, as !ong !ong as the$ the$ supp suppor ortt the the )OA& )OA& 6ocu 6ocume ment nt'' /itera /itera!! encodi encoding. ng. #ote #ote that that 3
Microsoft *isua! CK.#, !ie a!! p!a$ers in the .# p!atform has ece!!ent support for -eb )er(ices out of the bo. try    huE.huE9ommand0ervice huE.huE9ommand0ervice svc  svc = new new huE.  huE.huE9ommand0ervice huE9ommand0ervice>< ><  

huE.UserVo3en huE.UserVo3en to3en  to3en = new new huE.  huE.UserVo3en UserVo3en>< >< to3en.username = B0U/78B B0U/78B< < to3en.password = B0U/78B B0U/78B< < svc.UserVo3enWalue = to3en<

 

huE.processRnEoundD!#atahuE9ommand0ervice_processRnEoundD!#ata8esult huE.processRnEoundD!#atahuE9ommand0ervice_processRnEoundD!#ata8esult result = svc.processRnEoundD!#ata svc.processRnEoundD!#ataBfooB BfooB, , Bnative_fooB Bnative_fooB, , Bsys_idB Bsys_idB, , Bdwnld_infoB, Bdwnld_infoB , Brun_tran_fl5B Brun_tran_fl5B>< ><

A catch  catch  7Sception 7Sception e>  e>    9onsole.`rite!ineB7SceptionP 9onsole.`rite!ine B7SceptionP B + B + e>< A

In this case, hu# is hu# is a -eb %eference that is created b$ direct!$ referenc referencing ing the -)6/ from from the MOCA web web ser(er. It can be automatica!!$ updated whene(er the -)6/ changes.

Aut/enti0ation In the the CK eam eamp! p!e e abo(e abo(e,, the the ser( ser(ic ice e gene genera rate ted d b$ *isu *isua! a! )tudio.# had an additiona! propert$, propert$, 3serTo(en. 3serTo(en. hat hat is the current method of authentication for webser(ices. #ot a!! MOCA  web ser(ic ser(ices es reBuir reBuire e authen authentic ticatio ation, n, but authen authentic ticati ation on is an optiona! part of of each reBuest. reBuest. he seroen seroen object Fconsisting of username and password propertiesG is attached to the )OA& header header portion portion of each )OA& reBuest. reBuest. he message message bod$ itse!f  itse!f   just  just contai contains ns the operat operation ion reBues reBuest. t. -hen -hen the MOCA MOCA web ser( ser(ic ice e hand! hand!er er rece recei(e i(es s a ser ser oen oen,, it auth authen enti tica cate tes s the the reBu reBues estt b$ ca!! ca!!in ing g to the the MOCA MOCA comm comman and d lo5in weEservice weEservice. +$ defa defau! u!t, t, that that comp compon onen entt simp simp!$ !$ ca!! ca!!s s lo5in an$ (a!id a!id lo5in user, so an$

280

. E %

S E R * I C E S  

username and password can be used to eecute a web ser(ice. o !imit !imit acce access ss to web web ser( ser(ic ices es,, it is ad(is ad(isab ab!e !e to set set up an o(erri o(erridde dden n (ersio (ersion n of that that comman command d that that reBuir reBuires es dier dierent ent permissions than norma! app!ication access.

Appendi:  MOCA eb Servi0e Confi=uration DTD TX(ml version")%:" encodin$"E96;"X/ T54#4M4N service6confi$ serviceD/ T54#4M4N service operationD/ T5A#I& service name C7AA Z?4.EI?47 class C7AA ZIM#I47 packa$e C7AA ZIM#I47/ T54#4M4N operation inputX, command, outputX/ T5A#I& operation name C7AA Z?4.EI?47/ T54#4M4N input ar$ument1/ T54#4M4N ar$ument 4M!/ T5A#I& ar$ument name C7AA Z?4.EI?47 type strin$0inte$er0double0boolean Z?4.EI?47 column C7AA ZIM#I47 nullable true0false "false" / T54#4M4N command ZC7AA/ T54#4M4N output field1/ T5A#I& output class C7AA ZIM#I47 multirow C7AA ZIM#I47/ T54#4M4N field 4M!/ T5A#I& field name C7AA Z?4.EI?47 type strin$0inte$er0double0boolean Z?4.EI?47 column C7AA ZIM#I47 nullable true0false "true" /

281