서버 스크립트 호출하기 (RunScript / RunScriptEx)

page no.  131112670

📖 이 문서에서 다루는 내용

i-AUD 의 JScript 에서 ServerScript 를 호출하는 두 가지 API - RunScript 와 RunScriptEx 의 사용법을 설명합니다.

이럴 때 이 문서를 읽어보세요:

• 🗄️ DB 조회·저장 로직을 서버에서 실행하고 싶을 때
• 📧 메일 발송, 파일 업로드처럼 브라우저에서 직접 할 수 없는 작업을 위임할 때
• 🔧 여러 보고서에서 공통으로 쓰는 서버 로직을 설계할 때

1. 🔍 두 메서드의 차이
   RunScript 와 RunScriptEx 는 거의 동일하지만, 파라미터 전달 여부가 핵심 차이입니다.

   	RunScript	RunScriptEx
   파라미터 전달	❌ 불가능	✅ params 객체로 전달
   사용 시기	전달할 파라미터가 없거나 전역 파라미터만 사용 시	검색 조건, 처리 대상 등 추가 값을 서버에 넘길 때

   💡 권장

   특별한 이유가 없다면 RunScriptEx 를 사용하세요.

   파라미터가 없을 때는 빈 객체 {} 를 넘기면 됩니다. 나중에 파라미터를 추가해야 할 때 메서드 변경 없이 확장 가능합니다.

2. 📐 API 시그니처

   RunScript / RunScriptEx

   // 파라미터 없이 호출
   Matrix.RunScript(gridNames, scriptName, function(p) {
       if(p.Success == false){
           Matrix.Alert(p.Message);
           return
       }
       var ds = p.DataSet;
   });
   
   
   //파라미터와 함께 호출
   Matrix.RunScriptEx("GridName", "ServiceName",{"VS_CODE":"codevalue","VS_NAME":"name value"},  function(p) {
       if(p.Success == false){
           Matrix.Alert(p.Message);
           return
       }
       var ds = p.DataSet;
   });

   
   파라미터 요약

   파라미터	타입	필수	설명
   gridNames	string | string[]	✅	서버로 전송할 그리드 이름 ( 없으면 "" )
   scriptName	string	✅	실행할 서버 스크립트 이름
   params	object	RunScriptEx만	서버에 전달할 파라미터
   callBack	function	✅	서버 응답 처리 콜백

3. 🎯 scriptName 지정 방식

   scriptName 은 어떤 서버스크립트를 실행할지 지정합니다. 세 가지 형식이 있습니다.

   🔑 핵심 요약

   형식	예시	탐색 위치
   "스크립트명"	"doSave"	🏠 현재 보고서의 ServerScript
   "@스크립트명"	"@COMMON_UTIL"	🏠 현재 보고서의 ServerScript
   "@보고서코드@스크립트명"	"@RPT_COMMON@SEND_MAIL"	📂 다른 보고서의 ServerScript

   ---

    형식1 - 현재 보고서의 스크립트

   현재 보고서의 ServerScript 에서 해당 이름을 찾습니다. 일반적으로 가장 많이 쓰는 방식입니다.

   예제 코드

   Matrix.RunScriptEx("DataGrid1", "doSave",{},  function(p) {
       if(p.Success == false){
           Matrix.Alert(p.Message);
           return
       }
       var ds = p.DataSet;
   });

    형식2 - 보고서 코드 없이 스크립트명만 지정

   현재 보고서에 '@' 로 시작하는 이름으로 등록된 스크립트를 호출합니다.

   보고서 내부에서만 재사용하는 공통 유틸 스크립트를 관리할 때 사용합니다. (다른 보고서의 스크립트를 호출하려면 형식3을 사용해야 합니다. )

   예제 코드

   Matrix.RunScriptEx("", "@COMMON_UTIL",{},  function(p) {
       if(p.Success == false){
           Matrix.Alert(p.Message);
           return
       }
       var ds = p.DataSet;
   });

    형식3 - 다른 보고서의 스크립트 ⭐

   '@보고서코드@스크립트명' 형식은 지정한 보고서에 등록된 서버 스크립트를 호출합니다. 여러 보고서에서 공유할 공통 로직을 한 보고서에 모아두고 관리할 때 사용하는 핵심 패턴입니다.

   ⚠️ 반드시 지켜야 할 규칙 - 스크립트 이름 앞에 @ 붙이기

    다른 보고서에서 '@보고서코드@스크립트명'으로 호출할 스크립트는 반드시 이름을 '@'로 시작하도록 등록해야 안정적인 참조가 보장됩니다.

   예제 코드

   Matrix.RunScriptEx("", "@RPT_COMMON@SEND_MAIL",{},  function(p) {
       if(p.Success == false){
           Matrix.Alert(p.Message);
           return
       }
       var ds = p.DataSet;
   });

4. 📊 gridNames — 그리드 데이터 전송

   DataGrid에서 변경된 데이터를 서버로 함께 넘길 때 지정합니다.. 전송할 데이터가 없으면 빈 문자열 ("") 을 사용합니다.

   📝 ServerScript 에서 사용하기

   서버 스크립트에서는 req.getDataTable("그리드명") 으로 전달된 데이터를 가져와서 사용합니다.

   예제 코드  원본 펼치기

   // 그리드 사용 안함
   Matrix.RunScriptEx("", "doSearch", params, callBack);
   // 단일 그리드
   Matrix.RunScriptEx("GRD_EMPLOYEE", "doSave", params, callBack);
   // 복수 그리드 (콤마 구분 또는 배열)
   Matrix.RunScriptEx("GRD_MASTER,GRD_DETAIL", "doSave", params, callBack);
   Matrix.RunScriptEx(["GRD_MASTER", "GRD_DETAIL"], "doSave", params, callBack);

5. 📦 params — 파라미터 전달
   서버 스크립트에 전달할 값을 객체 형태로 지정합니다.

   예제 코드  원본 펼치기

   var params = {
       VS_DEPT_CODE: "D001",
       VN_YEAR: 2025,
       VS_FROM_DATE: "2025-01-01",
       VS_TO_DATE:   "2025-12-31"
   };
   Matrix.RunScriptEx("", "doSearch", params, function(p) {
       if(p.Success == false){
           Matrix.Alert(p.Message);
           return
       }
       var ds = p.DataSet;
   });

   서버에서는 아래와 같이 값을 받아서 사용합니다  원본 펼치기

   var req = Matrix.getRequest();
   var vsDeptCode = req.getParam("VS_DEPT_CODE");  // → "D001"
   var vnYear     = req.getParam("VN_YEAR");        // → "2025"

6. 🔄 콜백 처리
   서버 처리가 끝나면 콜백 함수가 실행됩니다. 콜백 인자 p 는 세 속성을 가집니다.

   속성	타입	설명
   p.Success	boolean	✅/❌ 서버 처리 성공 여부
   p.Message	string	💬 실패 시 오류 메시지
   p.DataSet	DataSet	📦 서버에서 반환한 데이터셋

7. 🏗️ 공통 서버 스크립트 패턴

   여러 보고서에서 동일하게 필요한 로직(메일 발송, 파일 업로드, 사용자 검증 등)을 하나의 전용 보고서에 모아두고 '@보고서코드@스크립트명' 으로 호출하는 방식입니다.

   📂 전체 구조 예시

   [공통 서비스 보고서 RPT_COMMON]

   ServerScript/

   @SEND_MAIL.ts ← 이름이 @로 시작 → 서버에 @SEND_MAIL.jsx로 저장
   @UPLOAD_FILE.ts ← 서버에 @UPLOAD_FILE.jsx로 저장
   @VALIDATE_USER.ts ← 서버에 @VALIDATE_USER.jsx로 저장

   
   

   [업무 보고서 RPT_EMP_MGMT]
   → Matrix.RunScriptEx("", "@RPT_COMMON@SEND_MAIL", ...)
   → Matrix.RunScriptEx("", "@RPT_COMMON@UPLOAD_FILE", ...)
   [업무 보고서 RPT_ORDER_MGMT]
   → Matrix.RunScriptEx("", "@RPT_COMMON@SEND_MAIL", ...)
   → Matrix.RunScriptEx("", "@RPT_COMMON@VALIDATE_USER", ...)

   📎 공통 스크립트 include

   같은 보고서 또는 다른 위치의 스크립트를 현재 스크립트에 인라인으로 포함합니다.

   예제 코드

   // 현재 보고서 폴더의 @COMMON_UTIL.jsx 를 포함
   <% @include file="@COMMON_UTIL" %>
   // SERVER_SCRIPT 폴더 기준 절대 경로로 포함
   <% @include file="/RPT_COMMON/@VALIDATE_USER" %>

   🔍 제약 사항

   📏 최대 100 단계까지만 include 가 가능하며, 이를 초과하면 오류가 발생합니다.

   🔁 동일한 파일을 반복해서 include 하는 경우 자동으로 차단하여 순환 참조를 방지합니다.

   🚫 보안상 '../' 경로는 사용할 수 없으며, 사용 시 오류가 발생합니다.

   🤫 include 대상 파일이 없을 경우에도 오류는 발생하지 않으며, 해당 부분은 빈 내용으로 처리됩니다.

8. ❓ 자주 묻는 질문 (FAQ)

    🤔 Q. 보고서 코드는 어디서 확인하나요?

   가장 간단한 방법은 i-AUD 디자이너에서 파일 다이얼로그를 열고, 헤더 영역에서 마우스 오른쪽 버튼을 클릭한 후 ‘코드’ 옵션을 활성화하여 확인하는 것입니다.

   

    🤔 Q. 콜백이 실행되지 않을 때 원인은?

   다음 순서로 점검해보세요:

   1. ✅ scriptName 오타 확인 (보고서 코드나 스크립트명 불일치)

   2. 🚀 공통 스크립트 보고서가 서버에 배포되어 있는지 확인

   3. 🔍 서버 스크립트에서 예외 발생 → AUD.log 확인

   4. 🔑 @로 시작하는 이름으로 등록되어 있는지 확인

    🤔 Q. 서버 오류를 클라이언트에서 받으려면?

   서버에서 Matrix.ThrowException("메시지") 를 호출하면 콜백의 p.Success === false, p.Message 에 내용이 전달됩니다.

   ServerScript

   Matrix.ThrowException("권한이 없습니다.");

   JScript

   Matrix.RunScriptEx("", "doAction", params, function(p) {
       if (!p.Success) {
           Matrix.Alert(p.Message);  // "권한이 없습니다."
           return;
       }
   });

    🤔 Q. params 에 배열이나 객체를 넘기려면?

   getParam() 은 항상 문자열을 반환하므로, 복잡한 타입은 JSON.stringify 로 직렬화해서 넘기고 서버에서 파싱합니다.

   JScript

   Matrix.RunScriptEx("", "doProcess", {
       VS_ITEMS: JSON.stringify([{ id: 1, name: "A" }, { id: 2, name: "B" }])
   }, callBack);

   ServerScript

   var vsItems = req.getParam("VS_ITEMS");         // 문자열로 수신
   var items   = JSON.parse(vsItems);              // 배열로 변환
   for (var i = 0; i < items.length; i++) {
       var item = items[i];
       // item.id, item.name 사용
   }

    🤔 Q. 서버 스크립트 실행 중 로그를 남기려면?

   Matrix.WriteLog() 를 사용합니다. 서버 로그 파일에 기록됩니다.

   ServerScript

   Matrix.WriteLog("처리 시작: " + vsUserId);
   Matrix.WriteLog("SQL 결과 건수: " + tResult.getRowCount());
   
   try {
       // ...
   } catch(e: any) {
       Matrix.WriteLog("오류 발생", e);   // 스택 트레이스까지 로그에 기록
       Matrix.ThrowException(e.message);
   }

9. 🔗 관련 문서

   📚 함께 읽으면 좋은 문서

   👉🏻 [i-AUD] 서버 스크립트 호출 시 파라미터를 함께 등록하는 API가 추가되었습니다.

   👉🏻 4-9. i-AUD 보고서 세션 변수, 전역 변수 사용방법

   👉🏻 [FileDialog] 보고서 코드 설정 기능
   

   👉🏻 Log Viewer
   

   👉🏻 사용자별 로그 분리

   👉🏻 Server Script

   👉🏻 Client Script