Caché ObjectScript Reference - InterSystems Documentation

More documents

Recommendations

Info

Caché ObjectScript Special VariablesYour error handlers can check for a particular string value you choose and take steps tohandle the particular condition appropriately.$ECODE String OverflowIf the length of the accumulated string in $ECODE exceeds 512 characters, the first newerror code that causes the string overflow replaces the current list of error codes in $ECODE.See Using Caché ObjectScript for more information about the maximum string data length.NotesCreating Your Own Error CodesThe format for the $ECODE special variable is a comma-surrounded list of one or moreerror codes. Error codes starting with the letter U are reserved for the user. All other errorcodes are reserved for CachéNon-null values that you use to set $ECODE should be distinguishable from the values Cachéautomatically generates. To ensure this, always prefix your error text with the letter U. Alsoremember to delineate your error code with commas. For example:SET $ECODE=",Upassword expired!,"WRITE !,"ECODE set to: ",$ECODESET $ECODE=""WRITE !,"ECODE cleared: ",$ECODECheck $ZERROR Rather Than $ECODE for Caché ErrorsYour error handlers should check $ZERROR rather than $ECODE for the most recent Cachéerror.See Also• ZTRAP command• $STACK function• $ESTACK special variable• $ZEOF special variable• $ZERROR special variable• $ZTRAP special variable• Error Handling in Using Caché ObjectScript• System Error Messages in Caché Error Reference422 Caché ObjectScript Reference
$ESTACK$ESTACKContains the number of context frames saved on the call stack from a user-defined point.$ESTACK$ESDescription$ESTACK contains the number of context frames saved on the call stack for your job froma user-defined point. You specify this point by creating a new copy of $ESTACK using theNEW command.The $ESTACK special variable is similar to the $STACK special variable. Both contain thenumber of context frames currently saved on the call stack for your job or process. Cachéincrements and restores both when changing context. The major difference is that you canreset the $ESTACK count to zero at any point by using the NEW command. You cannotreset the $STACK count.Context Frames and Call StacksWhen a Caché image is started, before any contexts have been saved on the call stack, thevalues of both $ESTACK and $STACK are zero. Each time a routine calls another routinewith DO, Caché saves the context of the currently executing routine on the call stack, increments$ESTACK and $STACK, and starts execution of the called routine in the newly-createdcontext. The called routine can, in turn, call another routine, and so on. Each time anotherroutine is called, Caché increments $ESTACK and $STACK and places more saved contextson the call stack.Issuing a DO command, an XECUTE command, or a call to a user-defined function establishesa new execution context. Issuing a GOTO command does not.As DO commands, XECUTE commands, or user-defined function references create newcontexts, Caché increments the values of $STACK and $ESTACK. As QUIT commandscause contexts to exit, Caché restores the previous contexts from the call stack and decrementsthe values of $STACK and $ESTACK.The $ESTACK and $STACK special variables cannot be modified using the SET command.Attempting to do so results in a error.Creating a New $ESTACKYou can create a new copy of $ESTACK in any context by using the NEW command. Cachétakes the following actions:Caché ObjectScript Reference 423
Page 1 and 2:
Caché ObjectScriptReferenceVersion
Page 3 and 4:
Table of ContentsSymbols and Abbrev
Page 5 and 6:
$ORDER ............................
Page 7 and 8:
$ZB ...............................
Page 9 and 10:
$ZUTIL(68,21) .....................
Page 11 and 12:
$ZUTIL(128,1) .....................
Page 13:
List of FiguresClient/Server Connec
Page 16 and 17:
Symbols and AbbreviationsSymbol""##
Page 18 and 19:
Symbols and AbbreviationsSymbol( )*
Page 21 and 22:
Symbols Used in Caché ObjectScript
Page 23 and 24:
Abbreviations Used in Caché Object
Page 25 and 26:
Abbreviations Used in Caché Object
Page 29 and 30:
Caché ObjectScript CommandsThis do
Page 31 and 32:
BREAKBREAK without an ArgumentArgum
Page 33 and 34:
BREAKNote:BREAK 0 is ineffective in
Page 35 and 36:
DescriptionCLOSE device releases ow
Page 37 and 38:
ArgumentspcAn optional postconditio
Page 39 and 40:
outine with or without parameter pa
Page 41 and 42:
The Argumentless DO CommandThe argu
Page 43 and 44:
DOMainSET x=1,y=2,z=3WRITE !,"In Ma
Page 45 and 46:
The DO command has a postconditiona
Page 47 and 48:
DO WHILE• QUIT command• Argumen
Page 49 and 50:
DO WHILEQUIT and GOTOThe QUIT comma
Page 51 and 52:
ELSEELSEClause of block-oriented IF
Page 53 and 54:
DescriptionFOR is a block-oriented
Page 55 and 56:
FORMainloopFOR {READ !,"Number: ",n
Page 57 and 58:
cution of the loop. The FOR loop te
Page 59 and 60:
a range with initial value, increme
Page 61 and 62:
ArgumentspcAn optional postconditio
Page 63 and 64:
GOTOtestgotoAWRITE !,"running A"DO
Page 65 and 66:
HALTIn the following example, HALT
Page 67 and 68:
HANGNote:You cannot express hangtim
Page 69 and 70:
ELSEIF and ELSE clauses are optiona
Page 71 and 72:
JOBMainloopNEW sex,ageREAD !,"What
Page 73 and 74:
JOBpcroutineroutine-paramsclassname
Page 75 and 76:
have a formal parameter list with t
Page 77 and 78:
JOBParameterprincipal-outputDescrip
Page 79:
a jobbed process, you can use param
Page 82 and 83:
Caché ObjectScript CommandsRemote
Page 84 and 85:
Caché ObjectScript Commands• If
Page 86 and 87:
Caché ObjectScript Commandsserver
Page 88 and 89:
Caché ObjectScript CommandsDescrip
Page 90 and 91:
Caché ObjectScript CommandsNotesKI
Page 92 and 93:
Caché ObjectScript CommandsThe nod
Page 94 and 95:
Caché ObjectScript CommandsLOCK Wi
Page 96 and 97:
Caché ObjectScript Commandslocknam
Page 98 and 99:
Caché ObjectScript Commands• Set
Page 100 and 101:
Caché ObjectScript Commands• ^c
Page 102 and 103:
Caché ObjectScript CommandsLocking
Page 104 and 105:
Caché ObjectScript CommandsMERGEMe
Page 106 and 107:
Caché ObjectScript CommandsInitial
Page 108 and 109:
Caché ObjectScript CommandsNEWCrea
Page 110 and 111:
Caché ObjectScript Commandssaves t
Page 112 and 113:
Caché ObjectScript CommandsIn the
Page 114 and 115:
Caché ObjectScript CommandsOPENAcq
Page 116 and 117:
Caché ObjectScript Commands• Dev
Page 118 and 119:
Caché ObjectScript Commandsmnespac
Page 120 and 121:
Caché ObjectScript CommandsFor som
Page 122 and 123:
Caché ObjectScript Commands• Wit
Page 124 and 125:
Caché ObjectScript CommandsQUITTer
Page 126 and 127:
Caché ObjectScript CommandsQUIT an
Page 128 and 129:
Caché ObjectScript CommandsTest WR
Page 130 and 131:
Caché ObjectScript CommandsThe var
Page 132 and 133:
Caché ObjectScript CommandsNote th
Page 134 and 135:
Caché ObjectScript CommandsA timeo
Page 136 and 137:
Caché ObjectScript CommandsType of
Page 138 and 139:
Caché ObjectScript CommandsReading
Page 140 and 141:
Caché ObjectScript CommandsSETAssi
Page 142 and 143:
Caché ObjectScript Commandswas cre
Page 144 and 145:
Caché ObjectScript Commandswith th
Page 146 and 147:
Caché ObjectScript CommandsFor exa
Page 148 and 149:
Caché ObjectScript CommandsThe fol
Page 150 and 151:
Caché ObjectScript CommandsDescrip
Page 152 and 153:
Caché ObjectScript CommandsTROLLBA
Page 154 and 155:
Caché ObjectScript CommandsArgumen
Page 156 and 157:
Caché ObjectScript CommandsSee Als
Page 158 and 159:
Caché ObjectScript CommandsSET ^a(
Page 160 and 161:
Caché ObjectScript CommandsThe par
Page 162 and 163:
Caché ObjectScript Commandsword) w
Page 164 and 165:
Caché ObjectScript Commands• Log
Page 166 and 167:
Caché ObjectScript Commands• VIE
Page 168 and 169:
Caché ObjectScript CommandsAfter r
Page 170 and 171:
Caché ObjectScript CommandsModen >
Page 172 and 173:
Caché ObjectScript CommandsQUIT an
Page 174 and 175:
Caché ObjectScript CommandsWRITEDi
Page 176 and 177:
Caché ObjectScript CommandsfA form
Page 178 and 179:
Page 180 and 181:
Page 182 and 183:
Caché ObjectScript CommandsMnemoni
Page 184 and 185:
Caché ObjectScript CommandsCode-1-
Page 186 and 187:
Caché ObjectScript CommandsAfter C
Page 188 and 189:
Caché ObjectScript CommandsXECUTE
Page 191 and 192:
Caché ObjectScript FunctionsA func
Page 193 and 194:
$ASCII$ASCIIReturns the character c
Page 195 and 196:
$ASCIISTSET String="ThIs Is a MiXeD
Page 197 and 198:
$BIT// Set a to [0,0,1,1]SET $BIT(a
Page 199 and 200:
ExamplesIf bitstring= [0,0,1,1,0],
Page 201 and 202:
If bitstring = [0,0,1,1,0], when se
Page 203 and 204:
$BITLOGICNote:When $BITLOGIC is sup
Page 205 and 206:
See Also• $BIT function• $BITCO
Page 207 and 208:
$CHARREAD "Input a number 1-3: ",xS
Page 209 and 210:
$CHARABCACYou can use decimal numer
Page 211 and 212:
$DATAStatusValue011011MeaningThe va
Page 213 and 214:
$DATAWhen executed, this code might
Page 215 and 216:
Because numbers generated by $DOUBL
Page 217 and 218:
$EXTRACT$EXTRACTExtracts specified
Page 219 and 220:
is an asterisk, $EXTRACT returns th
Page 221 and 222:
$EXTRACTSET x="ABCD"SET $EXTRACT(x,
Page 223 and 224:
$FACTOR• $ZEXP function• $ZLN f
Page 225 and 226:
$FIND$FINDFinds a substring by valu
Page 227 and 228:
$FNUMBER• $LIST function• $PIEC
Page 229 and 230:
You can include the decimal option
Page 231 and 232:
$GET$GETReturns the data value of a
Page 233 and 234:
$GETIF $GET(^client(i))="" { QUIT }
Page 235 and 236:
The num parameter can be a positive
Page 237 and 238:
$INCREMENTKILL xyzWRITE !,$INCREMEN
Page 239 and 240:
DescriptionThe $INUMBER function va
Page 241 and 242:
$INUMBER• No sign or parentheses.
Page 243 and 244:
In the following example, $INUMBER
Page 245 and 246:
$ISVALIDNUMSET a="certainly not an
Page 247 and 248:
$ISVALIDNUMmin and maxYou can speci
Page 249 and 250:
$NORMALIZE parses multiple trailing
Page 251 and 252:
the end of width. If the expression
Page 253 and 254:
In the following example, the first
Page 255 and 256:
$LIST• $LIST(list) returns the fi
Page 257 and 258:
If the value of the position parame
Page 259 and 260:
$LISTBUILDresults of $LISTBUILD are
Page 261 and 262:
In the following example, ZZDUMP sh
Page 263 and 264:
$LISTFINDSET x=$CHAR(0,0,0,1,16,27,
Page 265 and 266:
If the value of the startafter para
Page 267 and 268:
$LISTGET• $LISTFIND function• $
Page 269 and 270:
If the value of the position parame
Page 271 and 272:
$LISTNEXT$LISTNEXTRetrieves element
Page 273 and 274:
Description$LISTSAME compares the c
Page 275 and 276:
$LISTTOSTRING• $LISTNEXT• $LIST
Page 277 and 278:
$NAME$NAMEReturns the name value of
Page 279 and 280:
with a naked reference to return th
Page 281 and 282:
$NEXT$NEXTReturns the value of the
Page 283 and 284:
The scale parameter value causes th
Page 285 and 286:
• Trailing + and - signs: Both fu
Page 287 and 288:
• Rounding factor: an integer ind
Page 289 and 290:
leading and trailing zeros, and del
Page 291 and 292:
For unsubscripted local variables,
Page 293 and 294:
$ORDER$ORDER Uses Naked Global Refe
Page 295 and 296:
ParametersplistThe target string fr
Page 297 and 298:
In the following example, both $PIE
Page 299 and 300:
The following examples also returns
Page 301 and 302:
$QLENGTH$QLENGTHReturns the number
Page 303 and 304:
$QSUBSCRIPTCode< -1-10nReturn Value
Page 305 and 306:
ExampleThis example presents a gene
Page 307 and 308:
function uses a naked reference to
Page 309 and 310:
$REVERSE$REVERSEReturns the charact
Page 311 and 312:
or immediately after a $SELECT func
Page 313 and 314:
If successful, $SORTBEGIN returns a
Page 315 and 316:
$STACKDOXECUTE$$ECODEReturned when
Page 317 and 318:
$STACK$STACK Code String Arguments
Page 319 and 320:
$TEXTroutineIf specified alone, it
Page 321 and 322:
$TRANSLATE$TRANSLATEPerforms charac
Page 323 and 324:
$VIEW$VIEWReturns the contents of m
Page 325 and 326:
double quotes. If the length parame
Page 327 and 328:
$VIEWStart OPEN 63WRITE !,"Opening
Page 329 and 330:
Math and Time FunctionsThe followin
Page 331 and 332:
$ZARCSINREAD "Input a number: ",num
Page 333 and 334:
$ZCOS210-1returns 1.107148717794090
Page 335 and 336:
ParametersnAn angle in radians, spe
Page 337 and 338:
$ZDATE$ZDATEValidates date and conv
Page 339 and 340:
ParametershdateThe internal date fo
Page 341 and 342:
$ZDATE“Jan Feb Mar Apr May Jun Ju
Page 343 and 344:
$ZDATEerroptThis parameter suppress
Page 345 and 346:
oth of the above lines generate a
Page 347 and 348:
$ZDATE• $ZDATETIME function• $Z
Page 349 and 350:
is a date, the second integer is a
Page 351 and 352:
$ZDATEHSyntaxMmmmmMeaningFull name
Page 353 and 354:
When yearopt=5, endwin is a numeric
Page 355 and 356:
• If you specify an invalid dform
Page 357 and 358:
• You can use the $ZDATEH functio
Page 359 and 360:
• $ZDATETIME(hdatetime) returns t
Page 361 and 362:
$ZDATETIMEtformatA numeric value th
Page 363 and 364:
$ZDATETIMEThe monthlist string has
Page 365 and 366:
$ZDATETIMEmindateA numeric value th
Page 367 and 368:
ODBC date format (dformat=3) will a
Page 369 and 370:
$ZDATETIMEH$ZDATETIMEHValidates dat
Page 371 and 372:
$ZDATETIMEH• The format Mmm DD YY
Page 373 and 374:
$ZDATETIMEHValue678MeaningExpress t
Page 375 and 376:
$ZDATETIMEHstartwinA numeric value
Page 377 and 378:
• If you specify an otherwise val
Page 379 and 380:
$ZEXP$ZEXPReturns the natural logar
Page 381 and 382:
ParametersnumA string value or a nu
Page 383 and 384:
ExamplesThe following example write
Page 385 and 386: $ZPOWERgenerates an error.See Also
Page 387 and 388: values to the corresponding multipl
Page 389 and 390: an error. You can use the absolute
Page 391 and 392: $ZTIME$ZTIMEConverts the internal s
Page 393 and 394: In the examples that follow, Htime
Page 395 and 396: $ZTIMEH$ZTIMEHConverts a time value
Page 397: $ZTIMEHTime DelimiterBy default, Ca
Page 400 and 401: Routine, Debugging, and Other Comma
Page 434 and 435: Caché ObjectScript Special Variabl
Page 486 and 487:
Caché ObjectScript Special Variabl
Page 488 and 489:
Page 490 and 491:
Page 492 and 493:
Page 494 and 495:
Page 496 and 497:
Page 498 and 499:
Page 500 and 501:
Page 502 and 503:
Page 504 and 505:
Page 506 and 507:
Page 508 and 509:
Page 510 and 511:
Page 512 and 513:
Page 515 and 516:
Structured System VariablesA struct
Page 517 and 518:
the $ZNSPACE special variable to de
Page 519 and 520:
^$JOB• ZNSPACE command• $ZNSPAC
Page 521 and 522:
^$LOCKSET x=$QUERY(^$JOB(""))WRITE
Page 523 and 524:
The following example tests for the
Page 525 and 526:
DescriptionYou can use the ^$ROUTIN
Page 527:
^$ROUTINE• $ORDER function• $QU
Page 530 and 531:
System and Other Functionsnumbers,
Page 532 and 533:
System and Other FunctionsThe bit_o
Page 534 and 535:
System and Other FunctionsWRITE $ZB
Page 536 and 537:
System and Other Functions$ZCONVERT
Page 538 and 539:
System and Other FunctionsEncoding
Page 540 and 541:
System and Other FunctionsDescripti
Page 542 and 543:
System and Other FunctionsNote that
Page 544 and 545:
System and Other FunctionsDeclarati
Page 546 and 547:
System and Other Functionstypedef s
Page 548 and 549:
System and Other FunctionsError Mes
Page 550 and 551:
System and Other Functions$ZF(-2)Ex
Page 552 and 553:
System and Other Functions$ZF(-3) c
Page 554 and 555:
System and Other FunctionsEstablish
Page 556 and 557:
Page 558 and 559:
System and Other Functions$ZISWIDEC
Page 560 and 561:
System and Other FunctionsSee Also
Page 562 and 563:
System and Other FunctionsParameter
Page 564 and 565:
System and Other FunctionslangAn in
Page 566 and 567:
System and Other FunctionsZNSPACE "
Page 568 and 569:
System and Other Functions$ZPOSITIO
Page 570 and 571:
Page 572 and 573:
Page 574 and 575:
System and Other FunctionsFor VMS,
Page 576 and 577:
System and Other Functions$ZSTRIPRe
Page 578 and 579:
System and Other FunctionsSET str="
Page 580 and 581:
System and Other FunctionsReturn Va
Page 582 and 583:
System and Other FunctionsThus, if
Page 584 and 585:
Page 586 and 587:
System and Other FunctionsYou can u
Page 588 and 589:
System and Other FunctionsExamplesT
Page 590 and 591:
System and Other Functions$ZUTIL(18
Page 592 and 593:
System and Other FunctionsSET A="Fr
Page 594 and 595:
System and Other FunctionsthirdSpec
Page 596 and 597:
Page 598 and 599:
System and Other FunctionsExampleWR
Page 600 and 601:
System and Other FunctionsDatabase
Page 602 and 603:
System and Other FunctionsCluster L
Page 604 and 605:
System and Other FunctionsDirectory
Page 606 and 607:
System and Other FunctionsAny form
Page 608 and 609:
Page 610 and 611:
System and Other Functions• $ZUTI
Page 612 and 613:
System and Other FunctionsSubfuncti
Page 614 and 615:
System and Other FunctionsExampleTh
Page 616 and 617:
Page 618 and 619:
Page 620 and 621:
Page 622 and 623:
System and Other FunctionsError on
Page 624 and 625:
Page 626 and 627:
System and Other FunctionsWhen a ne
Page 628 and 629:
System and Other FunctionsUSER>XECU
Page 630 and 631:
System and Other FunctionsCaché pr
Page 632 and 633:
Page 634 and 635:
Page 636 and 637:
Page 638 and 639:
System and Other FunctionsThis func
Page 640 and 641:
Page 642 and 643:
Page 644 and 645:
Page 646 and 647:
System and Other FunctionsSubfuncti
Page 648 and 649:
Page 650 and 651:
System and Other Functions• $GET
Page 652 and 653:
Page 654 and 655:
System and Other Functionsor "RW" m
Page 656 and 657:
System and Other FunctionsReading f
Page 658 and 659:
Page 660 and 661:
Page 662 and 663:
Page 664 and 665:
Page 666 and 667:
System and Other Functionsprincipal
Page 668 and 669:
Page 670 and 671:
System and Other FunctionsTCOMMIT c
Page 672 and 673:
Page 674 and 675:
Page 676 and 677:
Page 678 and 679:
Page 680 and 681:
System and Other Functionsa $ZDATE
Page 682 and 683:
Page 684 and 685:
Page 686 and 687:
Page 688 and 689:
System and Other FunctionsThis conf
Page 690 and 691:
Page 692 and 693:
System and Other FunctionsNotes$ZUT
Page 694 and 695:
Page 696 and 697:
System and Other FunctionsWRITE $ZD
Page 698 and 699:
Page 700 and 701:
Page 702 and 703:
System and Other FunctionsEvery tim
Page 704 and 705:
Page 706 and 707:
Page 708 and 709:
Page 710 and 711:
System and Other Functions• $TEST
Page 712 and 713:
System and Other FunctionsValue6789
Page 714 and 715:
Page 716 and 717:
System and Other Functionsreturns:
Page 718 and 719:
Page 720 and 721:
Page 722 and 723:
Page 724 and 725:
System and Other FunctionsFlag67891
Page 726 and 727:
Page 728 and 729:
System and Other Functions8: regula
Page 730 and 731:
System and Other FunctionsUSER>WRIT
Page 732 and 733:
System and Other Functionsas the cu
Page 734 and 735:
System and Other Functions• Go to
Page 736 and 737:
System and Other FunctionsNote:Beca
Page 738 and 739:
Page 740 and 741:
Page 742 and 743:
System and Other FunctionsExampleTh
Page 744 and 745:
System and Other Functions• $ZLCH
Page 746 and 747:
System and Other FunctionsConversio
Page 748 and 749:
System and Other Functions$ZZENKAKU
Page 750 and 751:
The %ZLANG Language Extension Libra
Page 753 and 754:
Legacy Commands and FunctionsLegacy
Page 755 and 756:
DescriptionDO (legacy version)Note:
Page 757 and 758:
When a block ends, as indicated by
Page 759 and 760:
See Also• DO command• $TEST spe
Page 761 and 762:
FOR (legacy version)increment is po
Page 763 and 764:
len-2, only the last character will
Page 765 and 766:
FOR (legacy version)Incrementing wi
Page 767 and 768:
IF (legacy version)IF (legacy versi
Page 769 and 770:
DescriptionZQUIT (legacy command)No
Page 771 and 772:
ZQUIT (legacy command)For example:Z
Page 773 and 774:
$ZBITFIND (legacy function)$ZBITCOU
Page 775 and 776:
ParameterspositionValue or expressi
Page 777 and 778:
esulting bitstring is 1 in all posi
Page 779 and 780:
DescriptionThis page describes the
Page 781 and 782:
Page 783 and 784:
$ZUTIL(67,4) (legacy function)• $
Page 785 and 786:
$ZUTIL(67,5) (legacy function)pstat
Page 787 and 788:
$ZUTIL(67,6) (legacy function)$ZUTI
Page 789 and 790:
$ZUTIL(67,7,pid) returns a string c
Page 791 and 792:
Page 793 and 794:
Code6064687276808488961041081161401
Page 795 and 796:
$ZUTIL(67,12) (legacy function)$ZUT
Page 797 and 798:
ParameterspidA process ID number. T
Page 799 and 800:
ExamplesThe following is the hexade
Page 801 and 802:
SYS.Process MethodsYou can get the
Page 803 and 804:
See Also$ZUTIL(133) (legacy functio
Page 805 and 806:
or a counter's name or description
Page 807 and 808:
$ZUTIL(133) (legacy function)1. Cal
show all

Caché ObjectScript Reference - InterSystems Documentation

Create successful ePaper yourself

Delete template?

Save as template?