page no.
📖 이 문서에서 다루는 내용
i-AUD 의 JScript 에서 ServerScript 를 호출하는 두 가지 API - RunScript 와 RunScriptEx 의 사용법을 설명합니다.
이럴 때 이 문서를 읽어보세요:
- 🗄️ DB 조회·저장 로직을 서버에서 실행하고 싶을 때
- 📧 메일 발송, 파일 업로드처럼 브라우저에서 직접 할 수 없는 작업을 위임할 때
- 🔧 여러 보고서에서 공통으로 쓰는 서버 로직을 설계할 때
🔍 두 메서드의 차이
RunScript 와 RunScriptEx 는 거의 동일하지만, 파라미터 전달 여부가 핵심 차이입니다.RunScript RunScriptEx 파라미터 전달 ❌ 불가능 ✅ params 객체로 전달 사용 시기 전달할 파라미터가 없거나 전역 파라미터만 사용 시 검색 조건, 처리 대상 등 추가 값을 서버에 넘길 때 특별한 이유가 없다면 RunScriptEx 를 사용하세요.
파라미터가 없을 때는 빈 객체 {} 를 넘기면 됩니다. 나중에 파라미터를 추가해야 할 때 메서드 변경 없이 확장 가능합니다.
📐 API 시그니처
// 파라미터 없이 호출 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 ✅ 서버 응답 처리 콜백 🎯 scriptName 지정 방식
scriptName 은 어떤 서버스크립트를 실행할지 지정합니다. 세 가지 형식이 있습니다.
형식 예시 탐색 위치 "스크립트명" "doSave" 🏠 현재 보고서의 ServerScript "@스크립트명" "@COMMON_UTIL" 🏠 현재 보고서의 ServerScript "@보고서코드@스크립트명" "@RPT_COMMON@SEND_MAIL" 📂 다른 보고서의 ServerScript 현재 보고서의 ServerScript 에서 해당 이름을 찾습니다. 일반적으로 가장 많이 쓰는 방식입니다.
Matrix.RunScriptEx("DataGrid1", "doSave",{}, function(p) { if(p.Success == false){ Matrix.Alert(p.Message); return } var ds = p.DataSet; });현재 보고서에 '@' 로 시작하는 이름으로 등록된 스크립트를 호출합니다.
보고서 내부에서만 재사용하는 공통 유틸 스크립트를 관리할 때 사용합니다. (다른 보고서의 스크립트를 호출하려면 형식3을 사용해야 합니다. )
Matrix.RunScriptEx("", "@COMMON_UTIL",{}, function(p) { if(p.Success == false){ Matrix.Alert(p.Message); return } var ds = p.DataSet; });'@보고서코드@스크립트명' 형식은 지정한 보고서에 등록된 서버 스크립트를 호출합니다. 여러 보고서에서 공유할 공통 로직을 한 보고서에 모아두고 관리할 때 사용하는 핵심 패턴입니다.
다른 보고서에서 '@보고서코드@스크립트명'으로 호출할 스크립트는 반드시 이름을 '@'로 시작하도록 등록해야 안정적인 참조가 보장됩니다.
Matrix.RunScriptEx("", "@RPT_COMMON@SEND_MAIL",{}, function(p) { if(p.Success == false){ Matrix.Alert(p.Message); return } var ds = p.DataSet; });📊 gridNames — 그리드 데이터 전송
DataGrid에서 변경된 데이터를 서버로 함께 넘길 때 지정합니다.. 전송할 데이터가 없으면 빈 문자열 ("") 을 사용합니다.
서버 스크립트에서는 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);📦 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"🔄 콜백 처리
서버 처리가 끝나면 콜백 함수가 실행됩니다. 콜백 인자 p 는 세 속성을 가집니다.속성 타입 설명 p.Success boolean ✅/❌ 서버 처리 성공 여부 p.Message string 💬 실패 시 오류 메시지 p.DataSet DataSet 📦 서버에서 반환한 데이터셋 🏗️ 공통 서버 스크립트 패턴
여러 보고서에서 동일하게 필요한 로직(메일 발송, 파일 업로드, 사용자 검증 등)을 하나의 전용 보고서에 모아두고 '@보고서코드@스크립트명' 으로 호출하는 방식입니다.
[공통 서비스 보고서 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", ...)같은 보고서 또는 다른 위치의 스크립트를 현재 스크립트에 인라인으로 포함합니다.
// 현재 보고서 폴더의 @COMMON_UTIL.jsx 를 포함 <% @include file="@COMMON_UTIL" %> // SERVER_SCRIPT 폴더 기준 절대 경로로 포함 <% @include file="/RPT_COMMON/@VALIDATE_USER" %>
📏 최대 100 단계까지만 include 가 가능하며, 이를 초과하면 오류가 발생합니다.
🔁 동일한 파일을 반복해서 include 하는 경우 자동으로 차단하여 순환 참조를 방지합니다.
🚫 보안상 '../' 경로는 사용할 수 없으며, 사용 시 오류가 발생합니다.
🤫 include 대상 파일이 없을 경우에도 오류는 발생하지 않으며, 해당 부분은 빈 내용으로 처리됩니다.
❓ 자주 묻는 질문 (FAQ)
가장 간단한 방법은 i-AUD 디자이너에서 파일 다이얼로그를 열고, 헤더 영역에서 마우스 오른쪽 버튼을 클릭한 후 ‘코드’ 옵션을 활성화하여 확인하는 것입니다.
다음 순서로 점검해보세요:
1. ✅ scriptName 오타 확인 (보고서 코드나 스크립트명 불일치)
2. 🚀 공통 스크립트 보고서가 서버에 배포되어 있는지 확인
3. 🔍 서버 스크립트에서 예외 발생 → AUD.log 확인
4. 🔑
@로 시작하는 이름으로 등록되어 있는지 확인서버에서 Matrix.ThrowException("메시지") 를 호출하면 콜백의 p.Success === false, p.Message 에 내용이 전달됩니다.
Matrix.ThrowException("권한이 없습니다.");Matrix.RunScriptEx("", "doAction", params, function(p) { if (!p.Success) { Matrix.Alert(p.Message); // "권한이 없습니다." return; } });getParam() 은 항상 문자열을 반환하므로, 복잡한 타입은 JSON.stringify 로 직렬화해서 넘기고 서버에서 파싱합니다.
Matrix.RunScriptEx("", "doProcess", { VS_ITEMS: JSON.stringify([{ id: 1, name: "A" }, { id: 2, name: "B" }]) }, callBack);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 사용 }Matrix.WriteLog() 를 사용합니다. 서버 로그 파일에 기록됩니다.
Matrix.WriteLog("처리 시작: " + vsUserId); Matrix.WriteLog("SQL 결과 건수: " + tResult.getRowCount()); try { // ... } catch(e: any) { Matrix.WriteLog("오류 발생", e); // 스택 트레이스까지 로그에 기록 Matrix.ThrowException(e.message); }🔗 관련 문서
👉🏻 [i-AUD] 서버 스크립트 호출 시 파라미터를 함께 등록하는 API가 추가되었습니다.
👉🏻 4-9. i-AUD 보고서 세션 변수, 전역 변수 사용방법
👉🏻 Log Viewer
👉🏻 사용자별 로그 분리
|